Create a GitRepo Resource

Create GitRepo Instance

Git repositories are registered by creating a GitRepo resource in Kubernetes. Refer to the creating a deployment tutorial for examples.

Git Repository Contents has detail about the content of the Git repository.

The available fields of the GitRepo custom resource are documented in the GitRepo resource reference Adding A Private Git Repository

Fleet does not support SSH proxy server authentication when cloning adding-a-private-git-repositoryor Using Private Helm Repositories . Use HTTPS authentication with a username and password or a personal access token.

Proper Namespace

Git repos are added to the SUSE® Rancher Prime Continuous Delivery manager using the GitRepo custom resource type. The GitRepo type is namespaced. By default, Rancher will create two SUSE® Rancher Prime Continuous Delivery workspaces:

  • fleet-default contains all the downstream clusters that are already registered through Rancher.

  • fleet-local will contain the local cluster by default.

If you are using SUSE® Rancher Prime Continuous Delivery in a single cluster style, the namespace will always be fleet-local. Check here for more on the fleet-local namespace.

For a multi-cluster style, please ensure you use the correct repo that will map to the right target clusters.

Override Workload’s Namespace

The targetNamespace field will override any namespace in the bundle. If the deployment contains cluster scoped resources, it will fail.

It takes precendence over all other namespace definitions:

gitRepo.targetNamespace > fleet.yaml namespace > namespace in workload’s manifest > fleet.yaml defaultNamespace

Workload namespace definitions can be restricted with allowedTargetNamespaces in the GitRepoRestriction resource.

Adding A Private Git Repository

SUSE® Rancher Prime Continuous Delivery supports the following authentication mechanisms for private repositories: * HTTP basic auth * SSH auth keys * Github Apps

To use any of them, you have to create a secret in the GitRepo's namespace.

For example, to generate a private SSH key:

ssh-keygen -t rsa -b 4096 -m pem -C "user@email.com"

The private key format has to be in EC PRIVATE KEY, RSA PRIVATE KEY or PRIVATE KEY and should not contain a passphase.

Put your private key into secret, use the namespace the GitRepo is in:

kubectl create secret generic basic-auth-secret -n namespace-of-your-gitrepo --type=kubernetes.io/basic-auth --from-literal=username=$user --from-literal=password=$pat

Now the clientSecretName must be specified in the repo definition:

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: sample-ssh
  # This namespace is special and auto-wired to deploy to the local cluster
  namespace: fleet-local
spec:
  # Everything from this repo will be run in this cluster. You trust me right?
  repo: "git@github.com:rancher/fleet-examples"
  # or
  # repo: "ssh://git@github.com/rancher/fleet-examples"
  clientSecretName: ssh-key
  paths:
  - simple

Private key with passphrase is not supported.

The key has to be in PEM format.

Known hosts

SUSE® Rancher Prime Continuous Delivery supports putting known_hosts into ssh secret. Here is an example of how to add it:

Fetch the public key hash(take github as an example)

ssh-keyscan -H github.com

And add it into secret:

apiVersion: v1
kind: Secret
metadata:
  name: ssh-key
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  known_hosts: |-
    |1|YJr1VZoi6dM0oE+zkM0do3Z04TQ=|7MclCn1fLROZG+BgR4m1r8TLwWc= ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==

Using HTTP Auth

Create a secret containing username and password. You can replace the password with a personal access token if necessary. Also see HTTP secrets in Github.

kubectl create secret generic basic-auth-secret -n namespace-of-your-gitrepo --type=kubernetes.io/basic-auth --from-literal=username=$user --from-literal=password=$pat

Just like with SSH, reference the secret in your GitRepo resource via clientSecretName.

 spec:
   repo: https://github.com/fleetrepoci/gitjob-private.git
   branch: main
   clientSecretName: basic-auth-secret

When using BitBucket and access tokens, the username must be x-token-auth.

Using a GitHub App

The following fields are needed to enable Fleet to authenticate to GitHub using a GitHub App:

Name Secret field name Where to find it

app ID

github_app_id

On your app’s settings page, under App ID (numeric value).

app installation ID

github_app_installation_id

In the URL of the installation page for the app. For instance, if you have installed the app on a foo/bar repo, navigate to that repo’s settings → Integrations → Applications, open the page for the app; its URL will look like https://github.com/settings/installations/<digits>;: those digits are your app installation ID.

private key

github_app_private_key

Generated when creating the GitHub App, or from the app settings page, where a Generate a private key button is available.

See GitHub documentation for more details on creating a GitHub App.

With the necessary data at hand, create a secret containing those fields:

kubectl -n namespace-of-your-gitrepo create secret generic github-app-secret \
    --from-literal=github_app_id=<app-id> \
    --from-literal=github_app_installation_id=<installation-id> \
    --from-file=github_app_private_key=<path-to-private-key-file>

Ensure you reference that secret in your GitRepo resource via clientSecretName.

Using Custom CA Bundles

Validating a repository using a certificate signed by a custom Certificate Authority can be done by specifying a cabundle field in a GitRepo.

Note that if secrets specifying CA bundles exist, for instance if Fleet is installed with Rancher (see the respective pages on Using a Private CA Signed Certificate and Additional Trusted CA’s), Fleet will use those CA bundles if no CA bundle is specified in the GitRepo.

Using Private Helm Repositories

The credentials will be used unconditionally for all Helm repositories referenced by the gitrepo resource. Make sure you don’t leak credentials by mixing public and private repositories. Use different helm credentials for each path, or split them into different gitrepos, or use helmRepoURLRegex to limit the scope of credentials to certain servers.

For a private Helm repo, users can reference a secret with the following keys:

  1. username and password for basic http auth if the Helm HTTP repo is behind basic auth.

  2. cacerts for custom CA bundle if the Helm repo is using a custom CA.

Note that if secrets specifying CA bundles exist, for instance if Fleet is installed with Rancher (see the respective pages on Using a Private CA Signed Certificate and Additional Trusted CA’s), Fleet will use those CA bundles if no CA bundle is specified in the Helm secret.

  1. ssh-privatekey for ssh private key if repo is using ssh protocol. Private key with passphase is not supported currently.

For example, to add a secret in kubectl, run

kubectl create secret -n $namespace generic helm --from-literal=username=foo --from-literal=password=bar --from-file=cacerts=/path/to/cacerts --from-file=ssh-privatekey=/path/to/privatekey.pem

After secret is created, specify the secret to gitRepo.spec.helmSecretName. Make sure secret is created under the same namespace with gitrepo.

Use different helm credentials for each path

SUSE® Rancher Prime Continuous Delivery allows you to define unique credentials for each Helm chart path in a Git repository using the helmSecretNameForPaths field.

gitRepo.spec.helmSecretName will be ignored if gitRepo.spec.helmSecretNameForPaths is provided

Create a file named secrets-path.yaml that specifies credentials for each path in your GitRepo. Each key can be either:

  • an exact path, which must match the full path to a bundle directory (a folder containing a fleet.yaml file). The path may have more segments than the entry under paths:.

  • a glob matching one or more paths, useful when credentials need to be reused across multiple paths/bundles.

Refer to Go filepath.Match documentation for examples of supported syntax.

If more than one glob matches a given path in a Git repository, Fleet will order globs lexically and use credentials from the first match.

Example: For repository path world-domination/ui_charts and a secret containing the following keys, credentials under the second glob will be used:

world-domination/*_charts: # will not be used
  username: fleet-ci
  password: foo
  insecureSkipVerify: true
world-domination/*: # will be used, as `/*` will be sorted before `/*_charts`
  username: fleet-ci
  password: foo
  insecureSkipVerify: true

If a path listed in the GitRepo is not included in this file, whether through exact paths or glob matching, Fleet does not use credentials for it.

The file should be named secrets-path.yaml; otherwise Fleet will not be able to use it.
Example GitRepo resource
kind: GitRepo
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: gitrepo
  namespace: fleet-local
spec:
  helmSecretNameForPaths: test-multipasswd
  repo: https://github.com/0xavi0/fleet-examples
  branch: helm-multi-passwd
  paths:
  - single-cluster/test-multipasswd
Example secrets-path.yaml
single-cluster/test-multipasswd/passwd:
  username: fleet-ci
  password: foo
  insecureSkipVerify: true
Another example with two distinct paths
path-one: # path path-one must exist in the repository
  username: user
  password: pass
path-two: # path path-two must exist in the repository
  username: user2
  password: pass2
  caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCiAgICBNSUlEblRDQ0FvV2dBd0lCQWdJVUNwMHB2...
  sshPrivateKey: ICAgIC0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLQogICAgTUlJRFF6Q0NBaXNDRkgxTm5Y...

Supported fields per path:

Field Description

username

Registry or repository username

password

Registry or repository password

caBundle

Base64-encoded CA certificate bundle

sshPrivateKey

Base64-encoded SSH private key

insecureSkipVerify

Boolean value to skip TLS verification
To create the secret, run:
kubectl create secret generic test-multipasswd -n fleet-local --from-file=secrets-path.yaml

The secret must be created in the same namespace as the GitRepo resource.

If you use https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher and want to include this secret in your backups, label it with resources.cattle.io/backup: true:

kubectl label secret path-auth-secret -n fleet-local resources.cattle.io/backup=true

Ensure the backup is encrypted to protect sensitive credentials.

Storing Credentials in Git

It’s recommended not to store credentials in Git. Even if the repository is properly protected, secrets are at risk during cloning, etc. As a workaround, tools like SOPS can encrypt credentials.

Instead, reference secrets in the downstream cluster. For manifest-style and kustomize-style bundles, do this in the manifests, e.g., by mounting the secrets or referencing them as environment variables. Helm-style bundles can use valuesFrom to read values from a secret in the downstream cluster.

When using Kubernetes encryption at rest and storing credentials in Git, configure the upstream cluster to include several Fleet CRDs in the encryption resource list:

- secrets
- bundles.fleet.cattle.io
- bundledeployments.fleet.cattle.io
- contents.fleet.cattle.io

Backing up and restoring

When backing up and restoring Fleet with existing workloads, be they GitRepos or HelmOps, consider:

Kubernetes API server availability

A Fleet agent in a downstream cluster monitors a cluster-specific namespace on the upstream cluster. During a restore operation, changes made in the upstream cluster may affect deployments in downstream clusters, which could be updated or deleted based on incomplete state from upstream.

To prevent this, make the Kubernetes API server inaccessible to downstream clusters while a restore is running. Agents should not access the upstream cluster until all resources are re-created.

Pausing

A paused GitRepo will pause bundles and bundle deployments. This means:

  • Deleting a bundle deployment from a paused GitRepo: Fleet will not re-create the bundle deployment until the GitRepo is unpaused.

  • Deleting a bundle from a paused GitRepo: Fleet will delete the bundle deployments coming from that bundle, and will not re-create the bundle (nor bundle-deployments) until the GitRepo is unpaused.

Pausing a GitRepo only prevents bundles and bundle deployments from being created or updated. It only affects controller operations, not Fleet agent operations. To prevent user resources in a bundle from being deleted when deleting a bundle deployment, use keepResources.

Troubleshooting

See the Fleet Troubleshooting section Troubleshooting docs.