Last modified December 16, 2024

Add a new app template

This document is part of the documentation to use GitOps with Giant Swarm app platform. You can find more information about the app platform in our docs.

Add a new app template to the repository

To avoid duplication caused by adding the same application from scratch across all your clusters, you can prepare app templates providing a pre-configured version of an App. This also allows you to manage and version an app’s configuration even if the app itself isn’t yet installed in any cluster.

Example

An example of an app template is available in the gitops-template repository “bases/apps/ingress-nginx”.

Export environment variables

The management cluster, the organization and the workload cluster names are needed during the process. Also, the app name, catalog and namespace should be provided. The easiest way of providing them is by exporting them as environment variables:

export WC_NAME=CLUSTER_NAME
export APP_NAME="${WC_NAME}-APP_NAME"
export APP_VERSION=APP_VERSION
export APP_CATALOG=APP_CATALOG
export APP_NAMESPACE=APP_NAMESPACE

Setting up directory tree structure for managing apps

Go to the bases/apps directory and create a new directory for the new app template:

cd bases/apps/
mkdir ${APP_NAME}

Now, navigate to the newly created directory and use the kubectl-gs plugin to generate the App resource:

cd ${APP_NAME}/
kubectl gs template app \
--app-name ${APP_NAME} \
--catalog ${APP_CATALOG} \
--cluster-name ${WC_NAME} \
--name ${APP_NAME} \
--target-namespace ${APP_NAMESPACE} \
--version ${APP_VERSION} > appcr.yaml

Additionally you can provide a default configuration, and additional secrets for your application. Adding them to the previous command as follows:

--user-configmap <my-configmap-name>
--user-secret <my-secret-name>

Note: Including ${cluster_name} in the app name avoids collision between clusters running same apps within the same organization.

Reference the app configuration for more details about how to create the respective ConfigMaps or secrets.

After running the kubectl gs command you can observe the output has an App resource together with the ConfigMap. Instead, you could rely on the ConfigMap generator feature of Kustomize to generate it on the fly.

Warning: Kustomize can’t be used for the secrets as they need to be encrypted before commit. Refer to our adding an app docs to check how to do it.

In the last step it’s time to create the kustomization.yaml file, adding the optional Secret or ConfigMap as resources and/or using a ConfigMap generator to manage plain configuration:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
buildMetadata: [originAnnotations]
# default config block start - include if you provide default config
configMapGenerator:
  - files:
    - values=default_config.yaml
    name: ${cluster_name}-ingress-nginx-values
generatorOptions:
  disableNameSuffixHash: true
# default config block end
resources:
  - appcr.yaml
  - secret.enc.yaml # only if you provide the default secret
  # You can add here the configmap in case of generate it via kubectl gs command or manually

At this point, you should have an app template ready. Now, you can add a new app to a workload cluster using the template.