Quick-start guide


It’s quite straightforward to start using the ad-hoc configurations component.

The basic steps are outlined in the next section.

This guide assumes that you can compile catalogs locally. Additionally, this guide assumes that you have the cluster and tenant IDs as environment variables.

export TENANT_ID=<the tenant id>
export CLUSTER_ID=<the cluster id>

The component expects that all customizations are valid Kubernetes manifests. Customizations are copied to the cluster catalog without any further processing. Manifests without .metadata.namespace will be deployed in the default namespace on the cluster.


  1. Compile cluster catalog locally to get access to the tenant repository

    tempdir=$(mktemp -d)
    pushd "${tempdir}"
    commodore catalog compile ${CLUSTER_ID}
    To run commodore from any directory it should be in $PATH or an alias to a containerized Commodore.
  2. Enable the component in the cluster’s configuration in the tenant repository. The tenant repository should be at inventory/classes/${TENANT_ID}, if you’re following this guide.

      - adhoc-configurations
  3. Create the directory for storing cluster customizations

    1. If not specified otherwise, the component will use manifests as the root directory for customizations.

      When using the default configuration, the component will look for customizations for a cluster in directory ${CLUSTER_ID} inside the manifests directory.

      mkdir -p inventory/classes/${TENANT_ID}/manifests/${CLUSTER_ID}
    2. If, for some reason, you can’t or don’t want to use manifests as the root directory for customizations, you can change the root directory in parameters.adhoc_configurations.

          manifests_path: customizations/${cluster:name}

      You’ll have to create the matching directory in the tenant repository.

      mkdir -p inventory/classes/${TENANT_ID}/customizations/${CLUSTER_ID}
      if you don’t add the cluster’s id (${cluster:name}) somewhere in the manifests_path parameter, Commodore will always copy over all the files in the directory indicated by manifests_path.
  4. Now you can add manifests in the directory you’ve created in previous step.

    All files which are added in the customizations directory for the cluster are copied into the cluster catalog. Commodore doesn’t validate or process the files in the customizations directory.

  5. Commit changes in tenant repository and recompile cluster catalog

    commodore catalog compile ${CLUSTER_ID} --push --interactive
    # Finally, cleanup temp directory
    rm -r "${tempdir}"
  6. (VSHN-internal only for the moment) Submit feature request describing the ad-hoc configuration to the product team

    See the Project Syn at VSHN documentation for a detailed description of how to create a feature request.