Each available add-on has a directory with subdirectories for each available version of the add-on following the format /addons/<name>/<version>.
Each add-on is required to define at a minimum two files, install.sh and Manifest.
The Manifest file specifies a list of assets required by the add-on. These will be downloaded during CI and saved to the add-on directory. The built add-on package will include the assets, including images, from the Manifest, saved as tar archives.
Any other files in the <addon>/<version> subdirectory will be included in the package built for the add-on.
The package will be built and uploaded to s3://[bucket]/[(dist\|staging)]/[kURL version]/<addon>-<version>.tar.gz during CI.
It can be downloaded directly from S3 or by redirect from https://kurl.sh/dist/<name>-<version>.tar.gz.
The built package will include the images from the Manifest saved as tar archives.
The install.sh script can implement a set of Lifecycle Hooks.
The install.sh script must define a function named <add-on> that will perform the install.
For example, /addons/weave/2.5.2/install.sh defines the function named weave.
During installation, upgrades and joining additional nodes, the installer will first load all assets and container images from the add-on's directory and create the directory $DIR/kustomize/<add-on> for rendered add-on scripts.
It will then source the <add-on>/install.sh script and execute a set of add-on lifecycle hooks.
Functions relating to the add-on runtime can be found here. See the flow charts in ARCHITECTURE.md for more details.
The add-on function in kURL will first load all images from the add-on's images/ directory and create the directory <KURL_ROOT>/kustomize/<add-on>.
It will then dynamically source the install.sh script and execute the function named <add-on>.
- For online installs, the add-on package will be downloaded and extracted at runtime.
- For airgap installs, the add-on package will already be included in the installer bundle.
Fetch the add-on package archive from the object store or from the air-gap bundle and extract into /var/lib/kurl/addons.
This step is typically skipped if the add-on version has not changed since the previous run.
Load (bash source) the install.sh script.
Run the Troubleshoot.sh preflight spec from host-preflight.yaml.
Operations that are performed in the pre-init script include installing host packages or Kustomizing the Kubernetes distribution.
Kubectl apply this add-on to the cluster. This step is typically skipped if the add-on version and configuration has not changed since the previous run. This hook is unique in that implementation of this hook requires a function with the add-on name itself, for example function weave().
This step run instead of addon_install if the add-on version and configuration has already been applied.
Operations that are performed in the join script include installing host packages or Kustomizing the Kubernetes distribution.
Operations that are performed in the post-init script include but not limited to configuring other add-on resources.
Print end-user messages to the screen.
To be considered for production, an add-on must adhere to the following requirements:
- A template directory with a generate.sh script and corresponding workflow file for automated generation of new add-on versions.
- A Testgrid spec with adequate coverage for merging without human approval.
- A host-preflight.yaml file including system requirements and preflights for successful customer installations.
- A Troubleshoot spec file with collectors and analyzers for ease of troubleshooting customer issues.
- All shell functions defined in the add-on's install.sh script should be prefixed with the name of the add-on to avoid naming collisions, for example
function rook_dashboard_ready_spinner().
The manifest is comprised of a set of directives for downloading and storing assets in add-on package archives.
| Directive | Description |
|---|---|
| image [id] [image] | A container image saved as a tar archive |
| yum [package] | A package from a Yum repository |
| yum8 [package] | A package from a Yum 8 repository |
| yumol [package] | A package from a Yum Oracle Linux repository |
| apt [package] | A package from an Apt repository |
| asset [src] | A url or local path to a file |
| dockerout [dst] [Dockerfile] [--build-arg=VERSION] | A Dockerfile to build and save as a tar archive |
Kubernetes resources should be applied in the addon_install hook.
The DIR env var will be defined to the install root.
Any yaml that is ready to be applied unmodified should be copied from the add-on directory to the kustomize directory.
cp "$DIR/addons/weave/2.5.2/kustomization.yaml" "$DIR/kustomize/weave/kustomization.yaml"The insert_resources, insert_patches_strategic_merge and insert_patches_json_6902 functions can be used to add resources to the kustomization.yaml.
insert_resources "$DIR/kustomize/weave/kustomization.yaml" secret.yamlThe render_yaml_file_2 function can be used to substitute env vars in a yaml file at runtime.
render_yaml_file "$DIR/addons/weave/2.5.2/tmpl-secret.yaml" > "$DIR/kustomize/weave/secret.yaml"After the kustomize directory has been prepared with resources and patches and the kustomization.yaml file has been updated, the add-on should call kubectl apply -k to deploy its resources to the cluster.
Host packages can be installed using the install_host_archives function. They should be installed in either the addon_pre_init hook or the addon_install hook. Additionally, host packages can be installed in the addon_join hook if necessary on the secondary nodes.
install_host_archives "$DIR/addons/rook/$ROOK_VERSION" lvm2After adding a new version of an add-on, the versions.js file must be updated to make the version available to kURL.