Skip to main content
Version: 1.9.0

Install Epinio

Introduction​

Epinio is installed from a single Helm chart and, by default, it also installs Kubed, MinIO, Dex and a container registry in your Kubernetes cluster.

You can disable the installation of these sub charts by changing the settings as described in the respective sections.

Prerequisites​

See system requirements for a detailed list of external components your Kubernetes cluster needs to have before you install Epinio.

Installation​

Ingress Controller​

During installation via helm Epinio automatically creates various Ingress resources for its internal components. These components depend on a running ingress controller providing a default IngressClass.

You may install nginx-ingress-controller using LoadBalancer service type:

helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm upgrade --install nginx-ingress --namespace nginx-ingress nginx-stable/nginx-ingress \
    --set controller.setAsDefaultIngress=true \
    --create-namespace

It is also possible to use Traefik instead of Nginx following the official documentation.

Verify external loadbalancer IP assignment

Depending on your infrastructure and used Kubernetes offering it is recommended to verify if the service of the just deployed ingress controller has at least one EXTERNAL-IP address from the external loadbalancer provider (AWS ELB and similar) assigned to it.

kubectl get svc nginx-ingress-controller --namespace nginx-ingress
> NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP
> nginx-ingress-controller   LoadBalancer   10.43.223.228   <pending>

If you encounter the <pending> value in the EXTERNAL-IP column you can try one of the following steps to resolve that:

  • Enable the relevant cloud provider resources for your Kubernetes cluster
  • Install MetalLB loadbalancer into your Kubernetes cluster
  • Append --set "controller.service.externalIPs={<node1-ip>,<node2-ip>}" to the helm command above, or perform kubectl edit service nginx-ingress-controller -n nginx-ingress and add:
    spec:
      externalIPs:
      - <node1-ip>
      - <node2-ip>

Read more about this topic in the NGINX documentation.

Cert Manager​

Epinio needs cert-manager in order to create TLS certificates for the various Ingresses (see "Ingress controller" above).

If cert-manager is not already installed on the cluster, it can be installed like this:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager --namespace cert-manager  \
    --set installCRDs=true \
    --set extraArgs={--enable-certificate-owner-ref=true} \
    --create-namespace
caution

If cert-manager isn't installed in the namespace cert-manager, you have to set .Values.certManagerNamespace accordingly, otherwise Epinio installation will fail.

Dynamic storage provisioner​

To support Epinio a storage provisioner is needed. You can use any storage provisioner which provides, preferably, ReadWriteMany (RWX) Access Mode and a default StorageClass resource for dynamic storage provisioning.

info

To verify that your cluster provides a default StorageClass run the command kubectl get storageclass. The default StorageClass is marked with the string (default) next to its name in the output list.

As an example, you can deploy and configure local-path dynamic storage provisioner by running:

kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml
kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Install Epinio​

If the above dependencies are available or going to be installed by this chart, Epinio can be installed with the following:

helm repo add epinio https://epinio.github.io/helm-charts
helm repo update
helm upgrade --install epinio epinio/epinio --namespace epinio --create-namespace \
    --set global.domain=myepiniodomain.org
With "Let's Encrypt" certificates

To generate trusted TLS certificates with "Let's Encrypt" for your public domain set `.Values.global.tlsIssuer` to `letsencrypt-production` and your e-mail as value for `.Values.global.tlsIssuerEmail` key.

 helm upgrade --install epinio epinio/epinio --namespace epinio --create-namespace \
    --set global.domain=myepiniodomain.org \
    --set global.tlsIssuer=letsencrypt-production \
    --set global.tlsIssuerEmail=user@company.org

The only value that is mandatory is the .Values.global.domain which should be a wildcard *. enabled domain, pointing to the IP address of your running Ingress controller.

info
  • Use a non-default IngressClass: --set ingress.ingressClassName=<className>
  • Set annotations for Epinio related ingresses to resolve errors Entity Too Large when uploading application source code into Epinio:
    --set 'ingress.annotations.nginx\.ingress\.kubernetes\.io/proxy-body-size=1000m'

Read more on how to setup DNS here: DNS setup

NOTE: If you're deploying Epinio in a "localhost" environment, you can use a wildcard DNS service.

NOTE II: in case the installation fails due to an expired certificate (for instance if you have previously initialized the epinio cli on a machine for a different cluster) please consider executing epinio epinio settings update-ca. More info at: epinio-settings-update-ca

Verify Helm Chart Images​

This is done using the cosign tool. The following commands were tested using cosign version 2.1.1.

The three core Epinio images are epinio-server, epinio-unpacker, and epinio-ui. The general command to verify any of them is

cosign verify \
       --certificate-identity-regexp "https://github.com/epinio/epinio" \
       --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
       ghcr.io/epinio/(IMAGE):v1.9.0

where (IMAGE) is the name of the image to verify.

Installation on Specific Kubernetes Offerings​

Installing Epinio is a standard process as explained above, however you might need to configure it for a specific Kubernetes cluster.

To help you, see the following HowTos for various well-known Kubernetes clusters:

NOTE: The Public Cloud howto lists the three major Cloud providers but Epinio can run on any Kubernetes cluster.

Internal Epinio components​

Kubed​

Kubed is installed as a subchart when .Values.kubed.enabled is true (default). If you already have kubed running, you can skip the installation by setting the helm value .Values.kubed.enabled to false.

S3 storage​

Epinio is using an S3 compatible storage to store the application source code. This chart will install Minio when .Values.minio.enabled is true (default).

In addition to Minio, Epinio offers s3gw as another internal S3 compatible storage. It is installed when .Values.minio.enabled is set to false and .Values.s3gw.enabled is set to true.

Both choices for internal S3 compatible storage can be configured to use a user-defined storageClass. If no StorageClass is defined, the default storageClass is used. For Minio the custom storageClass is set via the value of .Values.persistance.storageClass. For s3gw the custom storageClass is set via the value of .Values.s3gw.storageClass.name.

Any external S3 compatible solution can be used instead by setting .Values.minio.enabled value to false (.Values.s3gw.enabled is false by default) and using the values under s3 to point to the desired S3 server.

Dex​

Dex OpenID Connect Provider is installed as a subchart when .Values.global.dex.enabled is set to true (default).

In case you don't need to use an identity provider you may set the value to false and use only local epinio users. OIDC Authentication provides more information.

Container Registry​

When Epinio builds a container image for an application from source, it needs to store that image to a container registry. Epinio installs a container registry on the cluster when .Values.containerregistry.enabled is true (default).

Any container registry that supports basic auth authentication (e.g. gcr, dockerhub, etc) can be used instead, by setting this value to false and using the relevant global values to point to the desired container registry.