Preparing the environment

Minikube

Minikube is a lightweight Kubernetes version that can run on a local machine.

Installation

Install minikube and run it:

minikube start --driver=docker

IMPORTANT: You need to make sure that Minikube uses a docker driver if it is already running on your system. Otherwise, you have to restart Minikube using the minikube delete command and start it using the command provided above.

The .kube/config file containing keys for connecting to the local cluster will be automatically created, allowing werf to connect to the local registry.

As a result, you must be able to access the cluster using the kubectl utility (you may need to install this utility separately). For example, the command below:

kubectl get ns

… will print a list of all namespaces in the cluster (and not an error message).

Ingress

You need to enable the appropriate addon in Minikube.

Registry

Enable the minikube registry addon:

minikube addons enable registry

And then perform the following actions depending on your operating system:

...
* Registry addon on with docker uses 32769 please use that instead of default 5000
...

docker run -ti --rm --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:32769"

kubectl -n kube-system expose rc/registry --type=ClusterIP --port=5000 --target-port=5000 --name=werf-registry --selector=actual-registry=true

kubectl port-forward --namespace kube-system service/werf-registry 5000

...
* Registry addon on with docker uses 32769 please use that instead of default 5000
...

docker run -ti --rm --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:32769"

brew install socat
socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:32769

sudo apt-get install -y socat
socat -d -d TCP-LISTEN:5000,reuseaddr,fork TCP:$(minikube ip):5000

Hosts

This tutorial assumes that the cluster (in fact, its Nginx Ingress controller) is located at example.com, and its registry is accessible at registry.example.com. We will be using this domain and its subdomains in the configs. In the case of using different addresses, adjust the configuration accordingly.

Enter the following lines in /etc/hosts:

127.0.0.1           example.com
127.0.0.1           registry.example.com

Authorizing in the registry

The Minikube registry does not require authorization. No further action is required.

Docker Desktop

Installing

Install Docker Desktop for Windows or macOS.

Start Kubernetes and configure the resources allocated to it.

The .kube/config file containing keys for connecting to the local cluster will be automatically created, allowing werf to connect to the local registry.

As a result, you must be able to access the cluster using the kubectl utility (you may need to install it separately). For example, the command below:

kubectl get ns

… will print the list of all namespaces in the cluster (and not an error message).

Ingress

You have to manually install the Nginx Ingress controller.

In the case of Docker Desktop, the Ingress controller may be inaccessible in some cases. That is because ports are not forwarded to the host machine. To make sure that Ingress works as intended, check that:

• The pod containing the Ingress controller is up and running fine (use this command for checking in the case of nginx-ingress: kubectl -n ingress-nginx get po).
• Kubernetes is listening on port 80 (check it with lsof -n | grep LISTEN or similar way)

If there is no Kubernetes on port 80 (HTTP), you may need to forward the port manually. For this, find out the name of the Ingress controller’s pod:

kubectl -n ingress-nginx get po

… and then run port forwarding:

kubectl port-forward --address 0.0.0.0 -n ingress-nginx ingress-nginx-controller-<random_alphanumeric_sequence> 80:80

After running the above commands, verify that an application is listening on port 80 (lsof -n | grep LISTEN).

Registry

Docker Desktop does not have a built-in registry. The easiest way is to run it manually as a Docker image:

docker run -d -p 5000:5000 --restart=always --name registry registry:2

Note that in this case, the registry does not use SSL encryption by default. Thus, you have to add the --insecure-registry=true parameter when using werf.

Hosts

This tutorial assumes that the cluster (in fact, its Nginx Ingress controller) is located at example.com, and its registry is accessible at registry.example.com. We will be using this domain and its subdomains in the configs. If you are using different addresses, adjust the configuration accordingly.

Insert the following lines in /etc/hosts:

127.0.0.1           example.com
127.0.0.1           registry.example.com

Authorizing in the registry

When running the registry in a local mode (as shown in the example above), no password is necessary, and you do not need to do anything.

docker login <registry_domain> -u <account_login> -p <account_password>

Choosing a cloud provider

There is many Managed Kubernetes offerings. Some of them include server capacity, while others don’t.

The easiest way is to take advantage of AWS (EKS) or Google (GKE) offerings. During the initial registration, they provide a bonus large enough for working with a cluster for a couple of weeks. However, you will need to enter your bank card details to register.

Yandex.Cloud is a viable alternative: the Managed Kubernetes service is available here as well, and you also must provide your card details. However, you can use some variation of a local bank card (such as the YouMoney card that allows for subscription payments within Russia).

You can also try to deploy Kubernetes yourself to the Hetzner cloud using their tutorial (Hetzner is one of the cheapest cloud providers out there). However, you must realize that you will have to deal with a large volume of platform administration tasks. You must find a reliable provider or support team for your production environment. If you have never installed Kubernetes yourself and/or do not have experience in system administration, then you should not try to master this rather voluminous topic as part of this tutorial.

Regardless of the cloud provider chosen, you will need to get the keys for accessing the Kubernetes cluster in the form of .kube/config file.

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: ALotOfNumbersAndLettersAndSoOnAveryVERYveryLongStringInBase64=
    server: https://127.0.0.1:6445
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: ManyNumbersAndLettersAVERYveryVerylongString=
    client-key-data: ManyLettersAndNumbersAveryVeryVERYlongString=

Checking the operability and access to the cluster

Check your cluster using the checklist provided at the beginning of the article.

As a result, you must be able to access the cluster using the kubectl utility (you may need to install this utility separately). For example, the command below:

kubectl get ns

… will print a list of all namespaces in the cluster (and not an error message).

Ingress

You also have to install Nginx Ingress in your cluster. There are detailed instructions available for all major providers on the NGINX Ingress Controller’s website.

Registry

In most cases, cloud providers provide a registry as one of the services (however, this is not always the case).

Ensure the network connectivity between the cluster and the registry: again, in most cases, the cloud provider solves this problem on its own or provides specific manuals on the subject.

Hosts

This tutorial assumes that the cluster (in fact, its Nginx Ingress controller) is located at example.com, and its registry is accessible at registry.example.com. You will have to choose and configure the necessary DNS records yourself and substitute your domains in the code throughout this tutorial.

Authorizing in the registry

You need to log in on the local machine using the docker login command so that werf can push assembled images to the registry:

docker login registry.example.com -u <account_login> -p <account_password>

where <account_login> is the login to the registry, and <account_password> is the password.

I have a cluster already

If you already have a cluster, then you probably have some experience in configuring it. Check your cluster using the checklist provided at the beginning of the article.

Regardless of how the cluster is installed, you will need to get the keys for accessing the Kubernetes cluster in the form of .kube/config file.

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: ALotOfNumbersAndLettersAndSoOnAveryVERYveryLongStringInBase64=
    server: https://127.0.0.1:6445
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: ManyNumbersAndLettersAVERYveryVerylongString=
    client-key-data: ManyLettersAndNumbersAveryVeryVERYlongString=

Checking the operability and accessibility of the cluster

Check your cluster using the checklist provided at the beginning of the article.

As a result, you must be able to access the cluster using the kubectl utility (you may need to install it separately). For example, the command below:

kubectl get ns

… must print a list of all namespaces in the cluster (and not an error message).

Ingress

Nginx Ingress must be installed in your cluster. The installation guide is available in the Kubernetes documentation.

Registry

werf supports various registry implementations.

Make sure that there is network connectivity between the cluster and the registry.

Hosts

This tutorial assumes that the cluster (in fact, its Nginx Ingress controller) is located at example.com, and its registry is accessible at registry.example.com. You will have to choose and configure the necessary DNS records yourself and substitute your domains in the code throughout this tutorial.

Authorizing in the registry

You need to log in to the local machine using the docker login command so that werf can push assembled images to the registry:

docker login <registry_domain> -u <account_login> -p <account_password>