Using and Creating ServiceTemplates: Creating and Deploying Applications

Deploying an application, like deploying a cluster, involves applying a template to the management cluster. Rather than a ClusterTemplate, however, applications are deployed using a ServiceTemplate.

You can find more information on Bringing Your Own Templates in the Template Guide, but this section gives you an idea of how to create a ServiceTemplate and use it to deploy an application to a k0rdent child cluster.

ServiceTemplate supports the following types as a source:

• HelmChart
• GitRespository
• Bucket
• OCIRepository
• Secret
• ConfigMap

Creating Helm-based ServiceTemplate

Note

Only HelmRepository support as a source for HelmChart.

Define the source of the Helm chart that defines the service. The source object must have the label k0rdent.mirantis.com/managed: "true". For example, this YAML describes a FluxCD source object of kind HelmRepository:

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: custom-templates-repo
  namespace: kcm-system
  labels:
    k0rdent.mirantis.com/managed: "true"
spec:
  insecure: true
  interval: 10m0s
  provider: generic
  type: oci
  url: oci://ghcr.io/external-templates-repo/charts

Create the ServiceTemplate

A template can either define a Helm chart directly using the template's spec.helm.chartSpec field or reference its location using the spec.helm.chartRef field.

For example:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ServiceTemplate
metadata:
  name: project-ingress-nginx-4.11.3
  namespace: my-target-namespace
spec:
  helm:
    chartSpec:
      chart: ingress-nginx
      version: 4.11.3
      interval: 10m0s
      sourceRef:
        kind: HelmRepository
        name: k0rdent-catalog

In this case, we're creating a ServiceTemplate called ingress-nginx-4.11.3 in the my-target-namespace namespace. It references version 4.11.3 of the ingress-nginx chart located in the k0rdent-catalog Helm repository.

For more information on creating templates, see the Template Guide.

Creating Kustomization-based ServiceTemplate

Define the source of the Kustomization that defines the service. If the source object is one of Flux source - GitRepository, Bucket or OCIRepository - it must have the label k0rdent.mirantis.com/managed: "true".

Source object can be already created. In this case .spec.kustomization.localSourceRef should be used:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ServiceTemplate
metadata:
  name: kustomization-app
  namespace: kcm-system
spec:
  kustomize:
    localSourceRef:
      kind: GitRepository
      name: project-x
    deploymentType: Remote
    path: "./base"

Aside from flux sources, local ConfigMap or Secret object can be used as a source of the kustomization manifests. The ServiceTemplate definition will not differ from one in above, except the .spec.kustomize.localSourceRef.kind which should be set to respective object type. However, to use ConfigMap or Secret as a source, they must embed archive with kustomization. After the archive was created, this can be done by executing the following command:

kubectl create configmap kustomization-source --from-file=/path/to/kustomization.tar.gz

Another option is to let the controller to create the remote source object. In this case .spec.kustomization.remoteSourceSpec should be used:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ServiceTemplate
metadata:
  name: kustomization-app
  namespace: kcm-system
spec:
  kustomize:
    remoteSourceSpec:
      oci:
        url: oci://ghcr.io/org/project-x
        reference:
          tag: latest
        interval: 10m
    deploymentType: Remote
    path: "./overlays"

When .spec.kustomize.remoteSourceSpec is defined, the controller will create corresponding object.

Creating Raw-Resources-based ServiceTemplate

This type of source is quite similar to the kustomization sources, with the only exception: when using ConfigMap or Secret as a source, the field .spec.resources.localSourceRef.path will be ignored and the resources' manifests to be deployed must be inlined in the source's data.

Example of the ConfigMap and corresponding ServiceTemplate:

apiVersion: v1
kind: ConfigMap
metadata:
  name: project-cm
  namespace: project-x
data:
  namespace.yaml: |
    apiVersion: v1
    kind: Namespace
    metadata:
      name: managed-ns

To create such ConfigMap the following command can be used:

kubectl --namespace project-x create configmap project-cm --from-file=/path/to/namespace.yaml

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ServiceTemplate
metadata:
  name: managed-ns
  namespace: project-x
spec:
  resources:
    localSourceRef:
      kind: ConfigMap
      name: project-cm
    deploymentType: Remote
    path: ""  # will be ignored

Using the remote source for ServiceTemplate based on raw resources is similar to the kustomization-based template:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ServiceTemplate
metadata:
  name: kustomization-app
  namespace: kcm-system
spec:
  resources:
    remoteSourceSpec:
      git:
        url: https://github.com/org/project-x.git
        reference:
          branch: main
        interval: 10m
    deploymentType: Remote
    path: "./overlays"

Deploying Application with ServiceTemplate

Create a ServiceTemplateChain

To let k0rdent know where this ServiceTemplate can and can't be used, create a ServiceTemplateChain object, as in:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ServiceTemplateChain
metadata:
  name: project-ingress-nginx-4.11.3
  namespace: my-target-namespace
spec:
  supportedTemplates:
    - name: project-ingress-nginx-4.11.3
    - name: project-ingress-nginx-4.10.0
      availableUpgrades:
        - name: project-ingress-nginx-4.11.3

Here you see a template called project-ingress-nginx-4.11.3 that is meant to be deployed in the my-target-namespace namespace. The .spec.helm.chartSpec specifies the name of the Helm chart and where to find it, as well as the version and other important information. The ServiceTempateChain shows that this template is also an upgrade path from version 4.10.0.

If you wanted to deploy this as an application, you would first go ahead and add it to the cluster in which you were working, so if you were to save this YAML to a file called project-ingress.yaml you could run this command on the management cluster:

kubectl apply -f project-ingress.yaml -n my-target-namespace

Adding a Service to a ClusterDeployment

To add the service defined by this template to a cluster, you would simply add it to the ClusterDeployment object when you create it, as in:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ClusterDeployment
metadata:
  name: my-cluster-deployment
  namespace: tenant42
spec:
  config:
    clusterLabels: {}
  template: aws-standalone-cp-0-2-0
  credential: aws-credential
  serviceSpec:
    services:
      - template: project-ingress-nginx-4.11.3
        name: ingress-nginx
        namespace: my-target-namespace
    priority: 100

As you can see, you're simply referencing the template in the .spec.serviceSpec.services[].template field of the ClusterDeployment to tell k0rdent that you want this service to be part of this cluster.

If you wanted to add this service to an existing cluster, you would simply patch the definition of the ClusterDeployment, as in:

kubectl patch clusterdeployment my-cluster-deployment -n my-target-namespace --type='merge' -p '{"spec":{"serviceSpec":{"services":[{"template":"project-ingress-nginx-4.11.3","name":"ingress-nginx","namespace":"my-target-namespace"}]}}}'

For more information on creating and using ServiceTemplate objects, see the User Guide.