# Adding a GitRepo ## Proper namespace Git repos are added to the Fleet manager using the `GitRepo` custom resource type. The `GitRepo` type is namespaced. By default, Rancher will create two Fleet workspaces: **fleet-default** and **fleet-local**. - `Fleet-default` will contain all the downstream clusters that are already registered through Rancher. - `Fleet-local` will contain the local cluster by default. Users can create new workspaces and move clusters across workspaces. An example of a special case might be including the local cluster in the `GitRepo` payload for config maps and secrets (no active deployments or payloads). :::warning While it's possible to move clusters out of either workspace, we recommend that you keep the local cluster in `fleet-local`. ::: If you are using Fleet in a [single cluster](./concepts.md) style, the namespace will always be **fleet-local**. Check [here](https://fleet.rancher.io/namespaces/#fleet-local) for more on the `fleet-local` namespace. For a [multi-cluster](./concepts.md) style, please ensure you use the correct repo that will map to the right target clusters. ## Create GitRepo instance Git repositories are register by creating a `GitRepo` following the below YAML sample. Refer to the inline comments as the means of each field ```yaml kind: GitRepo apiVersion: fleet.cattle.io/v1alpha1 metadata: # Any name can be used here name: my-repo # For single cluster use fleet-local, otherwise use the namespace of # your choosing namespace: fleet-local spec: # This can be a HTTPS or git URL. If you are using a git URL then # clientSecretName will probably need to be set to supply a credential. # repo is the only required parameter for a repo to be monitored. # repo: https://github.com/rancher/fleet-examples # Enforce all resources go to this target namespace. If a cluster scoped # resource is found the deployment will fail. # # targetNamespace: app1 # Any branch can be watched, this field is optional. If not specified the # branch is assumed to be master # # branch: master # A specific commit or tag can also be watched. # # revision: v0.3.0 # For a private registry you must supply a clientSecretName. A default # secret can be set at the namespace level using the GitRepoRestriction # type. Secrets must be of the type "kubernetes.io/ssh-auth" or # "kubernetes.io/basic-auth". The secret is assumed to be in the # same namespace as the GitRepo # # clientSecretName: my-ssh-key # # If fleet.yaml contains a private Helm repo that requires authentication, # provide the credentials in a K8s secret and specify them here. # Danger: the credentials will be sent to all repositories referenced from # this gitrepo. See section below for more information. # # helmSecretName: my-helm-secret # # Helm credentials from helmSecretName will be used if the helm repository url matches this regular expression. # Credentials will always be used if it is empty or not provided # # helmRepoUrlRegex: https://charts.rancher.io/* # # To add additional ca-bundle for self-signed certs, caBundle can be # filled with base64 encoded pem data. For example: # `cat /path/to/ca.pem | base64 -w 0` # # caBundle: my-ca-bundle # # Disable SSL verification for git repo # # insecureSkipTLSVerify: true # # A git repo can read multiple paths in a repo at once. # The below field is expected to be an array of paths and # supports path globbing (ex: some/*/path) # # Example: # paths: # - single-path # - multiple-paths/* paths: - simple # PollingInterval configures how often fleet checks the git repo. The default # is 15 seconds. # Setting this to zero does not disable polling. It results in a 15s # interval, too. # # pollingInterval: 15 # Paused causes changes in Git to not be propagated down to the clusters but # instead mark resources as OutOfSync # # paused: false # Increment this number to force a redeployment of contents from Git # # forceSyncGeneration: 0 # The service account that will be used to perform this deployment. # This is the name of the service account that exists in the # downstream cluster in the cattle-fleet-system namespace. It is assumed # this service account already exists so it should be create before # hand, most likely coming from another git repo registered with # the Fleet manager. # # serviceAccount: moreSecureAccountThanClusterAdmin # Target clusters to deploy to if running Fleet in a multi-cluster # style. Refer to the "Mapping to Downstream Clusters" docs for # more information. # # targets: ... ``` ## Adding Private Git Repository Fleet supports both http and ssh auth key for private repository. To use this you have to create a secret in the same namespace. For example, to generate a private ssh key ```text ssh-keygen -t rsa -b 4096 -m pem -C "user@email.com" ``` Note: 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: ```text kubectl create secret generic ssh-key -n fleet-default --from-file=ssh-privatekey=/file/to/private/key --type=kubernetes.io/ssh-auth ``` :::caution Private key with passphrase is not supported. ::: :::caution The key has to be in PEM format. ::: Fleet 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) ```text ssh-keyscan -H github.com ``` And add it into secret: ```text apiVersion: v1 kind: Secret metadata: name: ssh-key type: kubernetes.io/ssh-auth stringData: ssh-privatekey: known_hosts: |- |1|YJr1VZoi6dM0oE+zkM0do3Z04TQ=|7MclCn1fLROZG+BgR4m1r8TLwWc= ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ== ``` :::warning If you don't add it any server's public key will be trusted and added. (`ssh -o stricthostkeychecking=accept-new` will be used) ::: :::info If you are using openssh format for the private key and you are creating it in the UI, make sure a carriage return is appended in the end of the private key. ::: ### 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](./troubleshooting#http-secrets-in-github). kubectl create secret generic basic-auth-secret -n fleet-default --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 ## Using Private Helm Repositories :::warning 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. 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. 3. `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. :::note If you are using ["rancher-backups"](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher) and want this secret to be included the backup, please add the label `resources.cattle.io/backup: true` to the secret. In that case, make sure to encrypt the backup to protect sensitive credentials. # Troubleshooting See Fleet Troubleshooting section [here](./troubleshooting.md).