diff --git a/docs/enableexperimental.md b/docs/enableexperimental.md new file mode 100644 index 000000000..890036fe5 --- /dev/null +++ b/docs/enableexperimental.md @@ -0,0 +1,36 @@ +# 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 feaures is done usign extra environment variales 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..f6fa4a9d7 --- /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 might me interesting for users that either need to store big `Bundles` and could also be seen as the first step for a `OCIOps` feature in the future. + +Once the OCI regitry is enabled `Fleet` will use it as the source for storing `Bundle`'s resources. +It won't fallback to the default `etcd` version when something fails accessing the OCI registry. The user will get an error in that case to fix the possible error. + +## 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', + ], + }, ], };