Merge branch 'main' into issue-3590-2

docs/bundle-add.md

@@ -4,8 +4,13 @@ Bundles are automatically created by Fleet when a `GitRepo` is created. In most
 manually by the user. If you want to deploy resources from a git repository use a
 [GitRepo](https://fleet.rancher.io/gitrepo-add) instead.
 
+
 If you want to deploy resources without a git repository follow this guide to create a `Bundle`.
 
+:::note
+If you want to deploy resources without running a Fleet controller, also take a look at the [Fleet CLI](ref-bundle-stages#examining-the-bundle-lifecycle-with-the-cli).
+:::
+
 When creating a `GitRepo` Fleet will fetch the resources from a git repository, and add them to a Bundle.
 When creating a `Bundle` resources need to be explicitly specified in the `Bundle` Spec.
 Resources can be compressed with gz. See [here](https://github.com/rancher/rancher/blob/main/pkg/controllers/provisioningv2/managedchart/managedchart.go#L149-L153)

docs/gitrepo-content.md

@@ -202,9 +202,12 @@ __How changes are applied to `values.yaml`__:
 The targeting step can treat the values as a template and fill in information from the `clusters.fleet.cattle.io` resource. More information can be found in [Helm values templating](./ref-fleet-yaml#templating).
 This can be turned off in `fleet.yaml`, by setting `disablePreProcess`, e.g. to avoid conflicts with other templating languages.
 
+It is not necessary to reference a chart's own `values.yaml` via `valuesFiles:`. The `values.yaml` file contained in the
+chart will always be used as a default when the agent installs the chart.
+
 :::note Credentials in Values
 
-If the chart generates certificates or passwords in its templates, these values must be overriden. Otherwise the chart could be continuously deployed as these values change.
+If the chart generates certificates or passwords in its templates, these values must be overridden. Otherwise the chart could be continuously deployed as these values change.
 
 Credentials loaded from the downstream cluster with `valuesFrom` are by default encrypted at rest, when [data encryption](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) is enabled in Kubernetes. Credentials contained in the default `values.yaml` file, or defined via `values:` or `valuesFiles` are not, as they are loaded from the repository when the bundle is created.
 

docs/glossary.md

@@ -19,16 +19,33 @@ See [this definition](https://helm.sh/docs/topics/charts/) of a Helm chart.
 A cluster refers to:
 * a [Kubernetes cluster](https://kubernetes.io/docs/concepts/architecture/) managed by Fleet
 * a `Cluster` [resource](https://github.com/rancher/fleet/blob/main/pkg/apis/fleet.cattle.io/v1alpha1/cluster_types.go#L59) in Fleet's API, which Fleet uses to manage that Kubernetes cluster
-## Continuous Delivery
+
+## Continuous Delivery/Deployment
+
+Definitions and distinctions between Continuous _Delivery_ and Continuous _Deployment_ greatly vary, for instance
+depending on:
+* whether the deployment step is included in the process, and to which environment: production or other?
+* what triggers a deployment: is it a manual or automated step?
+
+This much is clear, though: Fleet's goal is to make it easier to automate deployments.
+
 ## Custom Resource
 
 See [this official definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
 In short, a custom resource is a resource defined for the purposes of an application (in our case Fleet), to extend the set of resources supported by the Kubernetes API (pods, deployments, services, etc).
+
 ## Custom Resource Definition
 
 See [this explanation](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) from the Kubernetes docs.
+
 ## Deployment
 
+A deployment may refer to:
+* a [Kubernetes deployment](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/),
+whether part of a user workload or part of Fleet itself, such as an agent deployment, controller deployments.
+* the action of deploying a user workload, which means Fleet reading configuration (`GitRepo`, `fleet.yaml`, etc) and,
+as a result, creating resources on target clusters.
+
 ## Downstream Cluster
 
 A downstream cluster is a Kubernetes cluster where user workloads will run, without any Fleet controllers living there. It is a target cluster for Fleet, where only a Fleet agent lives beside user workloads.
@@ -36,17 +53,29 @@ A downstream cluster is a Kubernetes cluster where user workloads will run, with
 ## fleet.yaml
 
 A `fleet.yaml` file lives in a git repository and stores options for a bundle and bundle deployments to be generated from that bundle. More information is available [here](https://fleet.rancher.io/ref-fleet-yaml).
+
 ## GitOps
+
+GitOps refers to git-triggered operations, where git is the source of truth and changes to a git repository lead to
+changes being applied to the state of one or more clusters.
+
 ## GitRepo
 
 A `GitRepo` is a Fleet-specific resource, to be used as an entry point to using Fleet.
 Creating a `GitRepo` pointing to a set of paths in a git repository enables Fleet to monitor those paths and deploy resources stored or referenced there.
+
 ## Label
 
+Refers to a [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
+
 ## Multi-Cluster
 
 A multi-cluster setup involves more than one cluster: the upstream cluster, needed to manage deployment of workloads, and at least one downstream cluster.
+
 ## Namespace
+
+Refers to a [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
+
 ## Reconcile
 
 Reconciling is used in the context of states in Kubernetes clusters. Reconciling a resource means updating it so that its _actual_ state matches its _expected_ state, be it from configuration, eg. from a git repository, chart, etc.
@@ -58,12 +87,27 @@ A resource's state may also depend on another resource, leading to additional re
 
 Cluster registration is the process of getting a Fleet agent, living in a downstream cluster, recognised by Fleet controllers in the upstream cluster.
 Once registration is complete for a downstream cluster, Fleet is able to deploy workloads to that cluster.
+
 ## Repository
+
+A repository may be:
+* a git repository, storing code, configuration or any kind of files and keeping track of changes made to those files
+through commits. Fleet can monitor a git repository for new commits pushed to a specific branch or revision, at one or
+more paths, through [GitRepo](./gitrepo-add.md) resources.
+* a Helm repository, hosting Helm charts and an index file referencing them. Fleet is able to install Helm charts and
+apply user-defined configuration to them.
+
 ## Resources
 
+This usually refers to Kubernetes resources, which may be:
+* core resources defined by Kubernetes itself, such as config maps, deployments, pods, services, etc
+* custom resources defined by individual applications, such as Fleet itself, which defines GitRepo, Bundle,
+Bundledeployment and a few others.
+
 ## Target
 
 Fleet uses this word in the context of determining where a workload will run. This represents a _destination_ cluster for a workload.
+
 ## Upstream Cluster
 
 A Kubernetes cluster where Fleet controllers run. This is the cluster where `GitRepo`s, bundles and bundle deployments are created.
@@ -74,4 +118,3 @@ Also called _management_ cluster.
 A workload represents what users want to deploy through Fleet. It may be a set of Helm charts, Kubernetes manifests, kustomize, etc, stored or referenced in a git repository.
 
 When a user creates a `GitRepo` resource pointing to that git repository, and subsequently when relevant changes are found in that repository, Fleet deploys workloads.
-## Workspace

docs/helm-ops.md

@@ -111,6 +111,14 @@ In this case, Helm options would be similar to this:
 When an OCI URL is provided in the `repo` field, a non-empty `chart` field will lead to an error in the HelmOps status,
 and no bundle being created.
 
+:::note
+In this case, Fleet will be downloading OCI artifacts. This means that:
+* the `version` field represents an OCI artifact's tag, which may be different to the actual version of the
+chart stored in the OCI artifact.
+* an OCI artifact may contain multiple Helm charts. This use case has only been validated with OCI artifacts containing
+  a single Helm chart.
+:::
+
 ## Polling
 
 Fleet can poll the referenced Helm registry, periodically checking if new versions are available.

docs/ref-fleet-yaml.md

@@ -335,6 +335,18 @@ It is possible to download the chart from a Git repository, e.g. by using
 `git@github.com:rancher/fleet-examples//single-cluster/helm`. If a secret for the SSH key was defined in the GitRepo via
 `helmSecretName`, it will be injected into the chart URL.
 
+:::note chart reference depending on `fleet.yaml` location
+If a `fleet.yaml` file is located outside of an embedded chart's directory, then it must explicitly reference the chart
+using a `helm.chart` field. Otherwise, Fleet will not install the chart.
+
+This also means that if no `helm.chart` field is specified in such a case, then Helm-specific fields like `valuesFiles`
+or `valuesFrom` will not have any effect.
+
+It is not necessary to specify a chart's own `values.yaml` via `valuesFiles:`. It will always be used as a default when the agent installs the chart. See [Using Helm Values](./gitrepo-content#using-helm-values).
+
+See [Using Helm Values](./gitrepo-content#using-helm-values) for more details.
+:::note
+
 :::warning Limitation: downloading Helm charts from git with custom CA bundles
 
 Git repositories can be downloaded via unauthenticated http, by using for example:
@@ -346,7 +358,7 @@ unable to get local issuer certificate` when running `fleet apply` to generate a
 
 See [fleet#3646](https://github.com/rancher/fleet/issues/3646) for more details.
 
-:::warning
+:::
 
 ##### version
 
@@ -358,7 +370,7 @@ containing the `+` character, Helm automatically replaces `+` with '_' before up
 
 You should use the version with the `+` in `fleet.yaml`, as the `_` character is not supported by semver and Fleet also
 replaces `+` with `_` when accessing the OCI registry.
-:::note
+:::
 
 #### How fleet-agent deploys the bundle
 

sidebars.js

@@ -17,8 +17,9 @@ module.exports = {
       label: 'Explanations',
       collapsed: false,
       items:[
-        'architecture',
         'concepts',
+        'glossary',
+        'architecture',
         'ref-bundle-stages',
         'gitrepo-content',
         'namespaces',

versioned_sidebars/version-0.11-sidebars.json

@@ -105,6 +105,10 @@
               "type": "doc",
               "id": "cli/fleet-cli/fleet_deploy"
             },
+            {
+              "type": "doc",
+              "id": "cli/fleet-cli/fleet_gitcloner"
+            },
             {
               "type": "doc",
               "id": "cli/fleet-cli/fleet_target"

versioned_sidebars/version-0.9-sidebars.json

@@ -100,6 +100,10 @@
                   "type": "doc",
                   "id": "cli/fleet-cli/fleet_apply"
                 },
+                {
+                  "type": "doc",
+                  "id": "cli/fleet-cli/fleet_cleanup"
+                },
                 {
                   "type": "doc",
                   "id": "cli/fleet-cli/fleet_test"