Merge branch 'main' into Update-CLI-docs

docs/fetch-helm-oci.md

@@ -0,0 +1,43 @@
+# Fetch Helm Charts from OCI Registries
+
+Fleet supports pulling Helm charts stored in OCI registries. OCI registries are commonly used to store and distribute container images. By using them for Helm charts, you can apply the same packaging, authentication, and distribution methods you already use for container images.
+
+Using OCI registries for Helm charts helps you:
+
+* Store charts alongside container images in the same registry.  
+* Use the same authentication and access control you already apply to container images.  
+* Push and pull charts using standard OCI commands, making them easy to distribute across environments.  
+* Manage charts in registries designed for high availability and global distribution.
+
+For more information about HelmOps with OCI registry, refer to [HelmOps](helm-ops.md#oci-registry)
+
+![A visual asset displaying flow of fetching Helm charts from an OCI registry](../static/img/fetch-Helm-from-OCI.svg)
+
+For example, if you manage multiple clusters with Fleet, developers can push Helm charts to an internal OCI registry. Fleet then pulls the charts directly from the registry and deploys them to downstream clusters.  
+This approach avoids maintaining a separate chart repository and reuses your existing registry infrastructure.
+
+
+## Helm chart in fleet.yaml
+
+To fetch Helm chart, you reference the chart like this in a fleet.yaml file:
+
+```bash
+helm:
+  chart: "oci://ghcr.io/fleetrepoci/guestbook"
+```
+
+You can use the version field to reference a specific chart version.
+
+```bash
+helm:
+  chart: "oci://ghcr.io/fleetrepoci/guestbook"
+  version: 0.1.0
+```
+
+Fleet pulls the chart from the OCI registry and deploys it to the targeted clusters.
+
+## Using authenticated registries
+
+If the OCI registry requires authentication, reference a Kubernetes secret in the GitRepo resource. Fleet uses this secret to pull the chart and deploy it to the targeted clusters.
+
+For more information, refer to [fleet.yaml with authentication](gitrepo-add.md#using-private-helm-repositories).  

docs/fine-tune-error.md

@@ -0,0 +1,162 @@
+# **Fine Tuning Error Detection**
+
+Fleet monitors the `status` field of deployed resources to determine whether a `Bundle` is healthy or in error. In certain cases, Fleet may interpret a condition in the status field as an error, even if it is expected or harmless.
+
+You can adjust this behavior in two ways:
+
+* Ignore conditions in `fleet.yaml`  
+* Customize error mappings with environment variables
+
+![A visual flow of fine tuning error detections](../static/img/fine-tune-error-flow.svg)
+
+:::note
+You should rarely need to configure readiness detection in Fleet with environment variables. If you do, open an issue or submit a pull request to help improve the default readiness detection.
+:::
+
+## **Ignore conditions in `fleet.yaml`**
+
+Use the `ignore.conditions` setting in the `fleet.yaml` file to tell Fleet to ignore specific conditions.
+
+```yaml
+# from https://fleet.rancher.io/ref-fleet-yaml
+
+# Ignore fields when monitoring a Bundle. This can be used when Fleet thinks
+# some conditions in Custom Resources makes the Bundle to be in an error state
+# when it shouldn't.
+ignore:
+
+  # Conditions to be ignored
+  conditions:
+
+    # In this example a condition will be ignored if it contains
+    # {"type": "Active", "status", "False"}
+    - type: Active
+      status: "False"
+```
+
+This method is useful when a custom resource or controller sets conditions that cause Fleet to mark a Bundle as failed, even though the resource is healthy.
+
+![A visual flow of ignore condition during fine tuning error detection](../static/img/fine-tune-error-ingore.svg)
+
+## **Configure error mapping with environment variables**
+
+In Fleet **v0.13**, error detection was enhanced to give you more control. You can use the environment variable  `CATTLE_WRANGLER_CHECK_GVK_ERROR_MAPPING` to customize how resource conditions are interpreted.
+
+This variable lets you define, by `Group`,`Version`,`Kind` (GVK), which condition values should be treated as errors or explicitly not treated as errors.
+
+Set this variable in your Fleet Helm chart deployment (`values.yaml`) using `extraEnv`. The value must be JSON.
+
+```yaml
+# Extra environment variables passed to the fleet pods.
+# extraEnv:
+# - name: OCI_STORAGE
+#   value: "false"
+```
+:::note
+This setting is global to all Fleet controllers and applies to every `GitRepo`. If you need to adjust error handling only for a specific Bundle, use the `ignoreConditions` option in `fleet.yaml` instead.
+:::
+
+### Merging behavior
+
+When you override mappings with `CATTLE_WRANGLER_CHECK_GVK_ERROR_MAPPING`:
+
+* New Conditions are merged with predefined conditions.  
+* Condition values are replaced for any condition you redefine.
+
+For example, consider the Default mapping: 
+
+`HelmChart.Failed=["True"]`
+
+This means `Failed=True` is treated as an error.
+
+When you override with:
+
+* `HelmChart.Failed=["False"]`  
+* `HelmChart.Ready=["False"]`
+
+This results in 
+
+* `Failed=["False"]` replaces the default mapping. This means **`Failed=False`** is now treated as an error.  
+* `Ready=["False"]` is added, so **`Ready=False`** is also treated as an error.  
+* Other conditions unchanged.
+
+### Disable error interpretation example
+
+Assume that every value of `Failed` was previously interpreted as an error, for example:
+
+```json
+{ "type": "Failed", "status": ["True", "False"] }
+```
+You can narrow this mapping to treat only `Failed=True` as an error by setting:
+
+```json
+[
+  {
+    "gvk": "sample.cattle.io/v1, Kind=Sample",
+    "conditionMappings": [
+      { "type": "Failed", "status": ["True"] } 
+    ]
+  }
+]
+```
+
+This configuration means only **`Failed=True`** is treated as an error. `Failed=False` is no longer considered an error.
+
+You can also disable errors for any value of `Failed` by
+
+```json
+{ "type": "Failed", "status": [""] } 
+
+```
+
+This configuration ensures that **no value of `Failed`** is treated as an error.
+
+:::note
+Overriding conditions only affects the default error mappings (refer to [Default error mappings](#default-error-mappings)). Fleet may still mark a resource as an error because other checks, such as those from the `kstatus` library, continue to run after your customization.
+:::
+
+### Enable error interpretation example
+
+```json
+[
+  {
+    "gvk": "sample.cattle.io/v1, Kind=Sample",
+    "conditionMappings": [
+      { "type": "Failed", "status": ["True"] }
+    ]
+  }
+]
+
+```
+
+Here, `Failed=True` is treated as an error.
+
+## Default error mappings {#default-error-mappings}
+
+Fleet adds default error mappings to interpret certain resource conditions in the `status` field as errors. These mappings are applied besides to other readiness checks, such as those performed by the Kubernetes `kstatus` library.
+
+The following default mappings apply:
+
+* **HelmChart** (`helm.cattle.io/v1`)  
+  * `JobCreated`: Neither `True` nor `False` is considered an error.  
+  * `Failed`: `True` is considered an error.  
+* **Node** (`v1`)  
+  * `OutOfDisk`: `True` is considered an error.  
+  * `MemoryPressure`: `True` is considered an error.  
+  * `DiskPressure`: `True` is considered an error.  
+  * `NetworkUnavailable`: `True` is considered an error.  
+* **Deployment** (`apps/v1`)  
+  * `ReplicaFailure`: `True` is considered an error.  
+  * `Progressing`: `False` is considered an error.  
+* **ReplicaSet** (`apps/v1`)  
+  * `ReplicaFailure`: `True` is considered an error.
+
+### Fallback mapping
+
+If a resource does not match the listed GVKs, Fleet applies a fallback mapping:
+
+* Any `Group` and `Version` with any kind
+
+  * `Stalled`: `True` is considered an error.  
+  * `Failed`: `True` is considered an error.
+

docs/gitrepo-add.md

@@ -9,6 +9,10 @@ to the [creating a deployment tutorial](./tut-deployment.md) for examples.
 
 The available fields of the GitRepo custom resource are documented in the [GitRepo resource reference](./ref-gitrepo.md)
 
+:::note
+Fleet does not support SSH proxy server authentication when cloning [private Git](#adding-a-private-git-repository) or [Helm](#using-private-helm-repositories) repositories. Use HTTPS authentication with a username and password or a personal access token.
+:::
+
 ### 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**.
@@ -41,8 +45,9 @@ 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.
+:::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:
 
@@ -83,25 +88,17 @@ The key has to be in PEM format.
 
 ### Known hosts
 
-:::warning
-
-If you don't add one or more public keys into the secret, any server's public key will be trusted and added. (`ssh -o
-stricthostkeychecking=yes` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
-`false`.
-
-:::
-
 Fleet supports injecting `known_hosts` into an SSH secret. Here is an example of how to add it:
 
 Fetch the public key hash (taking Github as an example)
 
-```text
+```bash
 ssh-keyscan -H github.com
 ```
 
 And add it into the secret:
 
-```text
+```yaml
 apiVersion: v1
 kind: Secret
 metadata:
@@ -212,7 +209,31 @@ Fleet allows you to define unique credentials for each Helm chart path in a Git
 If `gitRepo.spec.helmSecretNameForPaths` is defined, `gitRepo.spec.helmSecretName` is ignored.
 :::
 
-Create a file named `secrets-path.yaml` that specifies credentials for each path in your `GitRepo`. The keys must match the full path to a bundle directory (a folder containing a `fleet.yaml file`), which may have more segments than the entry under `paths:`. If a path listed in the GitRepo is not included in this file, Fleet does not use credentials for it.
+Create a file named `secrets-path.yaml` that specifies credentials for each path in your `GitRepo`. Each key can be either:
+- an exact path, in which case it must match the full path to a bundle directory (a folder containing a `fleet.yaml
+file`), which 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.
+[Here](https://pkg.go.dev/path/filepath#Match) are examples of supported syntax.
+:::info
+If more than one glob match a given path in a git repository, then 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:
+```yaml
+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, then Fleet
+does not use credentials for it.
 
 :::note
 The file should be named `secrets-path.yaml`, otherwise Fleet will not be able to use it.

docs/helm-ops.md

@@ -81,7 +81,7 @@ bundle will be created, aborting deployment.
 A Helm chart can also be referenced through its repository and chart name, with an optional version, which may be a
 static version or a version constraint.
 
-This is where polling can make sense, because referencing the chart using a repository allows Fleet to check the
+In this case, polling can make sense, because referencing the chart using a repository allows Fleet to check the
 repository's `index.yaml` for available versions matching the `version` field.
 
 Example:
@@ -114,6 +114,8 @@ and no bundle being created.
 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.
+* polling is supported: Fleet can check available OCI tags matching both the provided repository and version constraint
+on a regular basis, configured through the polling interval.
 * an OCI artifact may contain multiple Helm charts. This use case has only been validated with OCI artifacts containing
   a single Helm chart.
 :::
@@ -147,6 +149,14 @@ When polling is enabled, Fleet does the following at the configured interval:
         * with `false` with an error if a failure happened
     * updating the `Last Polling Time` field to the starting time of the last polling attempt, even if it failed.
 
+## Using private Helm repositories
+
+This works the same way as it does for gitOps, by referencing a Helm access secret through field `helmSecretName`.
+
+See [the gitOps docs](./gitrepo-add.md#using-private-helm-repositories) for more details.
+The part on using separate credentials for each path is not relevant though, since unlike a GitRepo, a HelmOp resource
+only references a single Helm chart.
+
 ## Status updates
 
 Creating a HelmOp resource leads to a bundle being created, if Helm options are valid and a chart version can be found.

sidebars.js

@@ -48,12 +48,14 @@ module.exports = {
         {type:'doc', id:'gitrepo-targets'},
         {type:'doc', id:'bundle-diffs'},
         {type:'doc', id:'oci-storage'},
+        {type:'doc', id:'fetch-helm-oci'},
         {type:'doc', id:'webhook'},
         {type:'doc', id:'imagescan'},
         {type:'doc', id:'bundle-add'},
         {type:'doc', id:'observability'},
         {type:'doc', id:'helm-ops'},
-        {type:'doc', id:'rollout'}
+        {type:'doc', id:'rollout'},
+        {type:'doc', id:'fine-tune-error'}
       ],
     },
     {

versioned_docs/version-0.10/gitrepo-add.md

@@ -85,7 +85,7 @@ The key has to be in PEM format.
 :::warning
 
 If you don't add one or more public keys into the secret, any server's public key will be trusted and added. (`ssh -o
-stricthostkeychecking=yes` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
+stricthostkeychecking=no` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
 `false`.
 
 :::

versioned_docs/version-0.11/gitrepo-add.md

@@ -85,7 +85,7 @@ The key has to be in PEM format.
 :::warning
 
 If you don't add one or more public keys into the secret, any server's public key will be trusted and added. (`ssh -o
-stricthostkeychecking=yes` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
+stricthostkeychecking=no` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
 `false`.
 
 :::

versioned_docs/version-0.12/gitrepo-add.md

@@ -86,7 +86,7 @@ The key has to be in PEM format.
 :::warning
 
 If you don't add one or more public keys into the secret, any server's public key will be trusted and added. (`ssh -o
-stricthostkeychecking=yes` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
+stricthostkeychecking=no` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
 `false`.
 
 :::

versioned_docs/version-0.13/gitrepo-add.md

@@ -83,14 +83,6 @@ The key has to be in PEM format.
 
 ### Known hosts
 
-:::warning
-
-If you don't add one or more public keys into the secret, any server's public key will be trusted and added. (`ssh -o
-stricthostkeychecking=yes` will be used), unless you install Fleet with chart value `insecureSkipHostKeyChecks` set to
-`false`.
-
-:::
-
 Fleet supports injecting `known_hosts` into an SSH secret. Here is an example of how to add it:
 
 Fetch the public key hash (taking Github as an example)

versioned_docs/version-0.13/helm-ops.md

@@ -81,7 +81,7 @@ bundle will be created, aborting deployment.
 A Helm chart can also be referenced through its repository and chart name, with an optional version, which may be a
 static version or a version constraint.
 
-This is where polling can make sense, because referencing the chart using a repository allows Fleet to check the
+In this case, polling can make sense, because referencing the chart using a repository allows Fleet to check the
 repository's `index.yaml` for available versions matching the `version` field.
 
 Example:
@@ -114,6 +114,8 @@ and no bundle being created.
 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.
+* polling is supported: Fleet can check available OCI tags matching both the provided repository and version constraint
+on a regular basis, configured through the polling interval.
 * an OCI artifact may contain multiple Helm charts. This use case has only been validated with OCI artifacts containing
   a single Helm chart.
 :::