Skip to main content

How to add new tool to the platform

kuberise.io uses app of apps pattern for ArgoCD to deploy several applications and platform services to one or multiple clusters and it is possible to add a new tool or service to the platform. In this tutorial I will show you how to add a new tool to your cluster. Assume that I want to add gitea as a platform tool to my local platform cluster called local-example.

Assumptions​

  1. I have a running local kubernetes cluster
  2. I have deployed kuberise.io to my kubernetes cluster
  3. I would like to add a new platform tool (for example gitea) to a platform cluster (for example local-example platform)

Summary​

  1. Add the declaration to the app-of-apps (to the default values.yaml and also the platform specific one)
  2. Add the values.yaml to the values folder (to the default one and also the platform specific one)
  3. Add Ingress (optional)
  4. Add Certificate (optional)

1. Add the declaration to the app-of-apps​

In the app-of-apps folder, there is a chart that will deploy all applications that are listed in the values files. Values files are divided into the default values.yaml file and the platform specific values file (in this example values-local-example.yaml) and the helm chart will merge these two files and then will consume it. So it doesn't matter if you declare your tool in any of them. But to be dry (don't repeat yourself), we put the part that is likely common for different platforms in values.yaml and the platform specific part in the values-local-example.yaml file.

In this example we add this to the app-of-apps/values.yaml:

# app-of-apps/values.yaml
  gitea:
    enabled: false
    repoURL: https://dl.gitea.io/charts
    namespace: gitea
    targetRevision: 10.1.4
    chart: gitea

This block is bellow the helmCharts: because it is a helm chart. If we wanted to deploy a kustomize we had to put the declaration under applications:

Then we add a block to the app-of-apps/values-local-example.yaml file with the same name and we just enable it. Because it is the only part that is changing from one platform to another one.

# app-of-apps/values-local-example.yaml
  gitea:
    enabled: true

For example, if you have several platform clusters and you would like to deploy different versions of gitea to those cluster, you have to add the targetRevision to the platform specific values file and change the version for each cluster.

2. Add the values.yaml to the values folder​

Similar to the app-of-apps, in values folder, there are default folder and local-example folder and values for all services are in these two folder and they will be merged when they are deployed. So, the values that are common for different cluster can be placed in default folder to avoid repeating them for each platform. If you use kuberise.io to deploy to only one cluster, then it doesn't matter how you split the values between these two folders but it is necessary that you create a values.yaml file in both of them even if it is an empty file.

In each values folder there two sub directories which are applications and platform. platform is the place for values of the platform tools like gitea or keycloak and the applications folder is the place for values of the business applications that are developed inside the company by developers.

In our gitea example I add this code to the values/defaults/platform/gitea/values.yaml:

# values/defaults/platform/gitea/values.yaml
persistence:
  enabled: true

and add platform specific configuration to the values file in values/local-example/platform/gitea/values.yaml:

# values/local-example/platform/gitea/values.yaml

# more configuration for gitea specific to the platform local-example

3. Add Ingress (optional)​

If the tool you are adding has a dashboard or web interface that needs to be accessed from outside the cluster or from public internet then you need to create ingress for that. you don't need to enable the ingress in the helm chart values and we do it in another way.

There is a helm chart called Ingresses that is responsible to create ingress for all platform and application services. The source of that helm chart is in templates/ingresses folder and the values file is in values/local-example/platform/ingresses/values.yaml file.

You need to add an ingress item to the list of ingresses in values file:

  services:
  # ...
  - name: gitea # (required)
    subdomain: gitea # (default is the name)
    namespace: gitea # (default is the name)
    annotations: # (optional)
      nginx.ingress.kubernetes.io/rewrite-target: /
    serviceName: gitea # (default is the name)
    port: 8080 # (default is 80)
    path: / # (default is /)
    ingressClassName: nginx # (default is nginx)
    secretName: gitea-tls # (default is "" then ingress-nginx will use the default certificate)
# ...

If any values is just gitea, then you can remove that values and the ingresses helm chart will use the name as default which is gitea here. For example here you can reduce it to this code:

  services:
  - name: gitea
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
    port: 8080
    secretName: gitea-tls

You need to refer to the helm chart of gitea to find the correct values for each of these fields.

4. Add Certificate (optional)​

If you are using local cluster like kind and minikube then you don't need to do anything for certificate because cert-manager uses a whildcard self-signed certificate that covers all the subdomains for all services. But if you are using let's encrypt, then wild card certificate is not possible for http-01 challenge. Either you have to use dns-01 challenge or add the list of subdomain to cover all your platform and applications urls. You can do it easily by adding the subdomain to the values of cert-manager. There is an example in values/aks-example/platform/cert-manager/values.yaml that you can see how it is done:

# values/aks-example/platform/cert-manager/values.yaml

selfSignedCertificate:
  enabled: false
  createCaCertificate: false

letsencryptProductionCertificate:
  enabled: true

subdomains:
  - "argocd"
  - "gitea"
  - "keycloak"
  - "grafana"

Then if you are using for example minikube.kuberise.dev as your domain, your gitea url will be https://gitea.minikube.kuberise.dev

This is it and now if you push to your git repository, ArgoCD will deploy gitea into your kubernetes cluster and if there is any mistake in the file names or path, you will see an error message in ArgoCD dashboard addressing that problem.

There is another way of deploying an external helm chart which is slightly different and it is how keycloak example is deployed. In that way, you create an empty helm chart in templates folder and make gitea a dependency of that helm chart. Its benefit is that, now you have a templates folder (templates/gitea/templates) which is a good place to add extra yaml files related to the gitea in the same folder. (for extra yaml files it is always possible to put it in values/local-example/platform/raw folder as well). Also in that way, the values of gitea should have extra indention and under gitea: name. because gitea now is a dependency and not the main chart.

Instead of external helm chart if you want to copy the source of a helm chart in your repository or write the whole helm chart from scratch then you can put the source of helm chart in templates folder and then in app-of-apps values file you need to use path: instead of chart: (look at keycloak example)