diff --git a/docs/enableexperimental.md b/docs/enableexperimental.md new file mode 100644 index 000000000..243eb6a92 --- /dev/null +++ b/docs/enableexperimental.md @@ -0,0 +1,37 @@ +# How to enable experimental features + +Fleet supports experimental features that are disabled by default and that can be enabled by the user. + +Enabling/disabling experimental features is done using extra environment variables that are available when deploying `rancher/fleet`. + +## Enabling an experimental feature + +At the moment we're writing this document, Fleet has OCI storage as an experimental feature. + +### Enabling when installing Fleet stand-alone + +All you need to do is to pass something like: +``` +--set-string extraEnv[0].name=EXPERIMENTAL_OCI_STORAGE \ +--set-string extraEnv[0].value=true \ +``` +to your helm install or update command. + +Please note you have to use `--set-string` because otherwise the boolean value won't work as expected. + +### Enabling when installing Fleet with Rancher + +You can also activate the experimental features in Fleet when installing Rancher. + +The parameters are the same, but you have to add the `fleet.` prefix. + +``` +--set-string fleet.extraEnv[0].name=EXPERIMENTAL_OCI_STORAGE \ +--set-string fleet.extraEnv[0].value=true \ +``` + +## Available experimental features + +Right now Fleet supports the following experimental features: + +* [`EXPERIMENTAL_OCI_STORAGE`](./oci-storage.md) \ No newline at end of file diff --git a/docs/oci-storage.md b/docs/oci-storage.md new file mode 100644 index 000000000..602befc3d --- /dev/null +++ b/docs/oci-storage.md @@ -0,0 +1,35 @@ +# OCI Storage + +## Summary + +Fleet stores by default the bundle resources in etcd twice. This is done via the k8s API and there is a size limit, depending on the etcd configuration. + +This feature will allow users to choose an OCI registry as storage for bundle resources. The bundle resource will have an empty resource list and a reference to the OCI repository server. The bundledeployment will not point to a content resource, but to an OCI repository server instead. + +When using this feature the bundle resources are stored once, in the configured OCI registry, and Fleet won't be tied to possible `etcd` size limitations. + +This may me interesting for users who need to store big `Bundles`, and could also be seen as the first step for an `OCIOps` feature in the future. + +Once the OCI registry is enabled, Fleet will use it as the source for storing `Bundle` resources. +When Fleet can't access the OCI registry, it won't fall back to default `etcd` storage. Instead, it will log errors so they can be fixed. + +## Configuring the OCI registry + +OCI registry values should be configured as an extra section in the `GitRepo` yaml. + +There are the fields involved: +``` +// when ociRegistry is defined Fleet will use oci registry as storage +ociRegistry: + // url is the OCI registry url. + url: "docker.io/your-user-here" + // secret name where the credentials for the OCI registry are. + // expects a generic secret with username and password keys set. + authSecretName: oci-secret + // basicHTTP allows Fleet to uses basic http connections to communicate + // with the registry (defaults to false) + basicHTTP: false + // insecureSkipTLS allows connections to the OCI registry + // without certs (defaults to false) + insecureSkipTLS: false +``` diff --git a/sidebars.js b/sidebars.js index 658134a65..9cd1f84be 100644 --- a/sidebars.js +++ b/sidebars.js @@ -90,6 +90,15 @@ module.exports = { "dirName": "changelogs/changelogs" } ] - } + }, + { + type: 'category', + label: 'Experimental Features', + collapsed: false, + items:[ + 'enableexperimental', + 'oci-storage', + ], + }, ], };