Deploy an app#

The CLI is still in early alpha, expect breaking changes!

Deployment automation is currently done through fluxcd and helm.

Requirements#

• An external container registry e.g ghcr.io
• A Dockerfile for your app
• A Helm chart that describes how to run your app (or generate one)
• Access to your ertia cluster (account configured with cluster access)

Example#

We provide an example application that you can use for reference.

• https://github.com/ertia-io/application-example

Authenticate against your cluster#

Tenant is usally your customer name.

ertia kubernetes login <env>.<tenant>.ext-ertia.cloud

A browser window will open where you will be prompted to login with your cluster credentials.

A kube config for the environment will be stored to file $XDG_DATA_HOME/ertia/tenants/<tenant>/kube.config.<env>.

Configure registry credentials#

In order for your cluster to be able to pull your registry artifacts, you need to give it access to your registry.

ertia app registry add apps-registry-credential <registry> \
  --env <env> \
  --username="" \
  --password=""

Github Container Registry#

You need to configure a classic github token PAT which will be used as your password. You can create a new token here.

Its recommended to setup a seperate github account, that only have read access to your application repositories.

Your token needs read:packages scope and expiration should be No expiration.

ertia app registry add apps-registry-credential ghcr.io \
  --env test \
  --username="my-github-username" \
  --password="my-github-pat"

.ertia directory#

The CLI expects a .ertia directory where it looks for configuration.

Run the following command within your projects root directory to initialize a new Ertia application and generate a .ertia directory that contains a application.yaml file and a default Helm chart.

ertia app init

The initializing command sets some default values in the application.yaml file, you might need to change some of these.

application.yaml#

The application.yaml file holds the configuration for how the CLI will build and deploy your application.

# .ertia/application.yaml
name: "<app-name>"
tenant: "<tenant>"

containers:
  default:
    name: "ghcr.io/<my-org>/images/my-project"
    containerFile: "../Dockerfile"
    buildContext: "../."
    pullSecretName: "apps-registry-credential"

flux:
  name: "ghcr.io/<my-org>/flux/my-project"
  pullSecretName: "apps-registry-credential"

helm:
  name: "ghcr.io/<my-org>/charts/my-project"
  chartPath: "./helm/<app-name>"
  valuesFile: "./helm/values.yaml"
  pullSecretName: "apps-registry-credential"
  image:
    repositoryPath: "image.repository"
    tagPath: "image.tag"
    pullSecretsPath: "imagePullSecrets"
  environments:
    <env>:
      valuesFile: "./values-<env>.yaml"

Helm Chart#

Your application needs to have a Helm chart which contains Kubernetes manifests that describe how to run your application.

If you do not already have an chart, Helm can generate one for you. If you used the ertia app init command a default Helm chart was generated for you.

To generate a new default Helm chart, run the following command.

helm create .ertia/helm/<app-name>

Value mappings#

If you are using the default helm generated chart you do not need to make any modifications to application.yaml

The CLI needs to be able to inject some values into your chart in order to work correctly. In order to do that the CLI needs to know where in your helm values yaml certain values are expected to be. These are configured in your application.yaml under helm.image.

• Container repository → helm.repositoryPath
• Container tag → helm.tagPath
• Container pull secret → helm.pullSecretsPath

Expose Webservice to the Internet#

In order to expose your application on a domain, you need to add an ingress to your chart. How you do this depends on the helm chart you are using.

For the most basic configuration you only need to set <MY-SUBDOMAIN>.

If you do not want your webservice to be fully accessable you can lock it down to require authentication through your Zitadel. You enable this by setting the following ingress annotations.

• nginx.ingress.kubernetes.io/auth-url
• nginx.ingress.kubernetes.io/auth-signin

ingress:
  enabled: true
  annotations:
    ingress.kubernetes.io/ssl-redirect: "true"
  # Force SSO login (Enfore authenticated access through Zitadel)
  #  nginx.ingress.kubernetes.io/auth-url: "https://auth-proxy.${FLUX_DEFAULT_INGRESS_DOMAIN}/oauth2/auth"
  #  nginx.ingress.kubernetes.io/auth-signin: "https://auth-proxy.${FLUX_DEFAULT_INGRESS_DOMAIN}/oauth2/start?rd=https://$host$uri"
  className: "${FLUX_DEFAULT_INGRESS_CLASS}"
  hosts:
    - host: "<MY-SUBDOMAIN>.${FLUX_DEFAULT_INGRESS_DOMAIN}"
      paths:
        - path: /
          pathType: Prefix

Some values such as ${FLUX_DEFAULT_INGRESS_DOMAIN} and ${FLUX_DEFAULT_INGRESS_CLASS} will be handled by ertia and should be left as is.

Install application#

The first step towards getting your application running is to install it to the environment.

ertia app install --env <env>

Do note that the installation will be broken until you have done your first initial deploy.

Build application#

In order to build your application run the following

ertia app build

Once built the directory .ertia/build-cache will hold your built artifacts. This directory should probably be added to .gitignore.

Deploy application#

Currently only versions built from the main branch of your project can be deployed. This will be fixed in a future CLI version.

Run the following to deploy your application

ertia app deploy --env <env>

Any changes will get picked up within 1 minute, but you can also trigger the cluster to pick them up instantly by curling the flux webhook url printed at the end of your deploy. Do note that anyone with access to this webhook URL can trigger a lookup of a new version.

You can view all your deployments through the Flux Web UI

https://flux-web.<env>.<tenant>.ext-ertia.cloud/resources?namespace=apps-flux