Connect to private sources

A private source needs credentials. You keep the credentials in a Secret, and SSH known_hosts data in a ConfigMap. The source object references them in spec.auth. convoy reads the Secret and the ConfigMap from the namespace of the source. This guide shows each auth type that convoy implements: basic, token and sshKey for Git, basic and token for a Helm repository, and token for an OCI registry. For the full list, see Credentials.

Before you start#

• convoy runs on your cluster.
• You can create Secrets, ConfigMaps and convoy sources in the namespace default.
• You have a credential for the private source: a password, an access token or an SSH private key.
• For SSH, you have the ssh-keyscan tool.

Steps#

The examples use the namespace default. The Secret, the ConfigMap, the source and the Release must be in the same namespace. convoy rejects references to other namespaces.

Git with basic auth#

The username is a literal string in the source. The password comes from a Secret.

# GitRepository with basic auth. The username is inline; the password is read
# from a Secret key.
apiVersion: v1
kind: Secret
metadata:
  name: git-basic
  namespace: default
type: Opaque
stringData:
  password: replace_me
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: GitRepository
metadata:
  name: private-repo-basic
  namespace: default
spec:
  url: https://git.example.com/example/private-repo.git
  auth:
    type: basic
    basic:
      username: deploy-bot
      passwordRef:
        name: git-basic
        key: password
  interval: 1m0s
  minSyncInterval: 30s

1. Copy the example to a local file.

2. Replace replace_me with your password.

3. Replace deploy-bot with your username.

4. Replace the URL with the URL of your repository.

5. Apply the file:

   sh

   kubectl apply -f gitrepository-auth-basic.yaml

Git with a token#

convoy sends the token as the HTTP basic auth password, with the username git. GitHub and GitLab personal access tokens work in this mode.

# GitRepository with token auth. The token is read from a Secret key and sent as
# the HTTP basic-auth password (works with GitHub/GitLab personal access tokens).
apiVersion: v1
kind: Secret
metadata:
  name: git-token
  namespace: default
type: Opaque
stringData:
  token: ghp_replace_me
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: GitRepository
metadata:
  name: private-repo-token
  namespace: default
spec:
  url: https://github.com/example/private-repo.git
  auth:
    type: token
    token:
      tokenRef:
        name: git-token
        key: token
  interval: 1m0s
  minSyncInterval: 30s

1. Copy the example to a local file.

2. Replace ghp_replace_me with your token.

3. Replace the URL with the URL of your repository.

4. Apply the file:

   sh

   kubectl apply -f gitrepository-auth-token.yaml

Git with an SSH key#

sshKey needs two references. sshKeyRef points to the private key in a Secret. knownHostsRef points to the known_hosts data in a ConfigMap. You must supply the ConfigMap. convoy always verifies the host key of the server.

# GitRepository with SSH key auth. Requires two things:
#   - a Secret holding the private key (sshKeyRef)
#   - a ConfigMap holding known_hosts (knownHostsRef) — MANDATORY: convoy verifies
#     the server host key against it (no insecure "ignore host key" mode).
# known_hosts must use PLAINTEXT host entries (hashed |1|… entries are rejected).
# Get the entries with, e.g.: ssh-keyscan github.com
apiVersion: v1
kind: Secret
metadata:
  name: git-ssh
  namespace: default
type: Opaque
stringData:
  identity: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...replace with your private key...
    -----END OPENSSH PRIVATE KEY-----
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: git-known-hosts
  namespace: default
data:
  known_hosts: |
    github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: GitRepository
metadata:
  name: private-repo-ssh
  namespace: default
spec:
  url: ssh://git@github.com/example/private-repo.git
  auth:
    type: sshKey
    sshKey:
      sshKeyRef:
        name: git-ssh
        key: identity
      knownHostsRef:
        name: git-known-hosts
        key: known_hosts
  interval: 1m0s
  minSyncInterval: 30s

1. Read the host keys of the Git server:

   sh

   ssh-keyscan github.com > known_hosts

2. Make sure that each line starts with the host name.

3. Do not use the -H option of ssh-keyscan. convoy does not accept hashed entries.

4. Create the ConfigMap:

   sh

   kubectl create configmap git-known-hosts --from-file=known_hosts=known_hosts

5. Use a private key without a passphrase.

6. Create the Secret:

   sh

   kubectl create secret generic git-ssh --from-file=identity=id_ed25519

7. Copy only the GitRepository document of the example to a local file.

8. Replace the URL with the SSH URL of your repository.

9. Apply the file:

   sh

   kubectl apply -f gitrepository-auth-ssh.yaml

Helm repository with basic auth#

convoy sends the username and the password as HTTP basic auth.

# HelmRegistry with basic auth (username inline, password from a Secret). For a
# token instead, use `type: token` with `token.tokenRef` — it is sent as a Bearer
# header.
apiVersion: v1
kind: Secret
metadata:
  name: helm-basic
  namespace: default
type: Opaque
stringData:
  password: replace_me
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: HelmRegistry
metadata:
  name: private-charts
  namespace: default
spec:
  url: https://charts.example.com
  auth:
    type: basic
    basic:
      username: deploy-bot
      passwordRef:
        name: helm-basic
        key: password
  interval: 1m0s
  minSyncInterval: 30s

1. Copy the example to a local file.

2. Replace replace_me with your password.

3. Replace deploy-bot with your username.

4. Replace the URL with the URL of your chart repository.

5. Apply the file:

   sh

   kubectl apply -f helmregistry-auth-basic.yaml

For a token, set type: token and replace the basic block with this block:

token:
  tokenRef:
    name: helm-token
    key: token

convoy sends the token in an Authorization: Bearer header.

OCI registry with a token#

convoy authenticates to the registry with the username convoy and the token as the password.

# OCIRegistry with token auth. The token is read from a Secret key and used as the
# registry login password (registries accept a token as the password). For
# username+password, use `type: basic` with `basic.username` + `basic.passwordRef`.
apiVersion: v1
kind: Secret
metadata:
  name: oci-token
  namespace: default
type: Opaque
stringData:
  token: replace_me
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: OCIRegistry
metadata:
  name: private-oci-charts
  namespace: default
spec:
  url: oci://ghcr.io/example/charts
  auth:
    type: token
    token:
      tokenRef:
        name: oci-token
        key: token
  defaultContentType: helm
  interval: 1m0s
  minSyncInterval: 30s

1. Copy the example to a local file.

2. Replace replace_me with your token.

3. Replace the URL with the oci:// URL of your registry and repository path.

4. Apply the file:

   sh

   kubectl apply -f ociregistry-auth-token.yaml

For a username and a password, set type: basic with basic.username and basic.passwordRef.

Use the source in a Release#

1. Set spec.source of the Release to the name of the source.
2. Use the namespace of the Release for the source.

spec:
  source:
    type: gitRepository
    gitRepository:
      name: private-repo-token
      namespace: default
      ref:
        branch: main

For a full Release, see Deploy from Git or Deploy a Helm chart.

Check the result#

1. List the Git and Helm sources:

   sh

   kubectl get gitrepositories,helmregistries

2. Make sure that the READY column shows True.

3. Read the Ready condition of a source that is not ready:

   sh

   kubectl get gitrepository private-repo-token -o yaml

The reason of the Ready condition tells you the cause:

• Verified: convoy reached the source with your credentials.
• VerifyFailed: convoy cannot reach the source, or the source rejected the credentials. A missing Secret, ConfigMap or key also gives this reason. convoy tries again.
• Unsupported: convoy cannot use the configuration. Examples are an auth type that convoy does not implement, a key that convoy cannot parse, and hashed known_hosts entries. convoy does not try again with backoff. Fix the configuration.

The message of the condition gives the details. For a host key that does not match, the message names the host.

A Release does not wait for Ready=True on its source. When convoy cannot download the content, the Release reports Applied=False with reason SourceNotReady. Run kubectl get releases and read the APPLIED column.

Clean up#

1. Delete the source:

   sh

   kubectl delete gitrepository private-repo-token

2. Delete the Secret:

   sh

   kubectl delete secret git-token

3. For SSH, delete the ConfigMap:

   sh

   kubectl delete configmap git-known-hosts

Do the same steps for the other sources and Secrets that you created.

Next steps#

• Sources: how convoy verifies a source and fetches content.
• Credentials: the auth types of each kind.
• Deploy to a remote cluster: credentials for a Cluster.