Merge pull request #35 from rancher/update-versioned-docs

Update versioned docs

docs/gitrepo-add.md

@@ -121,7 +121,7 @@ spec:
   # targets: ...
 ```
 
-## Adding private git repository
+## 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.
 

versioned_docs/version-0.4/gitrepo-add.md

@@ -62,8 +62,9 @@ spec:
   # 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. Details are provided
+  # provide the credentials in a K8s secret and specify them here.
-  # in the fleet.yaml documentation.
+  # Danger: the credentials will be sent to all repositories referenced from
+  # this gitrepo. See section below for more information.
   #
   # helmSecretName: my-helm-secret
   #
@@ -120,7 +121,7 @@ spec:
   # targets: ...
 ```
 
-## Adding private repository
+## 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.
 
@@ -197,6 +198,28 @@ Just like with SSH, reference the secret in your GitRepo resource via `clientSec
       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. As a workaround, split them into different gitrepos.
+:::
+
+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.
+
+
 # Troubleshooting
 
 See Fleet Troubleshooting section [here](./troubleshooting.md).

versioned_docs/version-0.4/gitrepo-structure.md

@@ -1,5 +1,11 @@
 # Expected Repo Structure
 
+Fleet will create bundles from a git repository. This happens either explicitly by specifying paths, or when a `fleet.yaml` is found.
+
+Each bundle is created from paths in a GitRepo and modified further by reading the discovered `fleet.yaml` file.
+Bundle lifecycles are tracked between releases by the helm releaseName field added to each bundle. If the releaseName is not
+specified within fleet.yaml it is generated from `GitRepo.name + path`. Long names are truncated and a `-<hash>` prefix is added.
+
 **The git repository has no explicitly required structure.** It is important
 to realize the scanned resources will be saved as a resource in Kubernetes so
 you want to make sure the directories you are scanning in git do not contain
@@ -78,7 +84,7 @@ helm:
   # value of `chart` will be used as the chart name to lookup in the Helm repository.
   repo: https://charts.rancher.io
   # A custom release name to deploy the chart as. If not specified a release name
-  # will be generated.
+  # will be generated by combining the invoking GitRepo.name + GitRepo.path.
   releaseName: my-release
   # The version of the chart or semver constraint of the chart to find. If a constraint
   # is specified it is evaluated each time git changes.
@@ -95,7 +101,7 @@ helm:
   valuesFiles:
     - values1.yaml
     - values2.yaml
-  # Allow to use values files from configmaps or secrets
+  # Allow to use values files from configmaps or secrets defined in the downstream clusters
   valuesFrom:
   - configMapKeyRef:
       name: configmap-values
@@ -200,27 +206,14 @@ dependsOn:
   - name: one-multi-cluster-hello-world
 ```
 
-:::info
+### Private Helm Repositories
 
-For a private Helm repo, users can reference a secret with the following keys:
+For a private Helm repo, users can reference a secret from the git repo resource.
-
+See [Using Private Helm Repositories](gitrepo-add#using-private-helm-repositories) for more information.
-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.
-
-:::
 
 ### Using ValuesFrom
 
-These examples showcase the style and format for using `valuesFrom`.
+These examples showcase the style and format for using `valuesFrom`. ConfigMaps and Secrets should be created in downstream clusters.
 
 Example [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/):
 

versioned_docs/version-0.5/gitrepo-add.md

@@ -62,8 +62,9 @@ spec:
   # 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. Details are provided
+  # provide the credentials in a K8s secret and specify them here.
-  # in the fleet.yaml documentation.
+  # Danger: the credentials will be sent to all repositories referenced from
+  # this gitrepo. See section below for more information.
   #
   # helmSecretName: my-helm-secret
   #
@@ -120,7 +121,7 @@ spec:
   # targets: ...
 ```
 
-## Adding private repository
+## 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.
 
@@ -197,6 +198,28 @@ Just like with SSH, reference the secret in your GitRepo resource via `clientSec
       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. As a workaround, split them into different gitrepos.
+:::
+
+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.
+
+
 # Troubleshooting
 
 See Fleet Troubleshooting section [here](./troubleshooting.md).

versioned_docs/version-0.5/gitrepo-structure.md

@@ -1,5 +1,11 @@
 # Expected Repo Structure
 
+Fleet will create bundles from a git repository. This happens either explicitly by specifying paths, or when a `fleet.yaml` is found.
+
+Each bundle is created from paths in a GitRepo and modified further by reading the discovered `fleet.yaml` file.
+Bundle lifecycles are tracked between releases by the helm releaseName field added to each bundle. If the releaseName is not
+specified within fleet.yaml it is generated from `GitRepo.name + path`. Long names are truncated and a `-<hash>` prefix is added.
+
 **The git repository has no explicitly required structure.** It is important
 to realize the scanned resources will be saved as a resource in Kubernetes so
 you want to make sure the directories you are scanning in git do not contain
@@ -78,7 +84,7 @@ helm:
   # value of `chart` will be used as the chart name to lookup in the Helm repository.
   repo: https://charts.rancher.io
   # A custom release name to deploy the chart as. If not specified a release name
-  # will be generated.
+  # will be generated by combining the invoking GitRepo.name + GitRepo.path.
   releaseName: my-release
   # The version of the chart or semver constraint of the chart to find. If a constraint
   # is specified it is evaluated each time git changes.
@@ -200,27 +206,14 @@ dependsOn:
   - name: one-multi-cluster-hello-world
 ```
 
-:::info
+### Private Helm Repositories
 
-For a private Helm repo, users can reference a secret with the following keys:
+For a private Helm repo, users can reference a secret from the git repo resource.
-
+See [Using Private Helm Repositories](gitrepo-add#using-private-helm-repositories) for more information.
-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.
-
-:::
 
 ### Using ValuesFrom
 
-These examples showcase the style and format for using `valuesFrom`.
+These examples showcase the style and format for using `valuesFrom`. ConfigMaps and Secrets should be created in downstream clusters.
 
 Example [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/):