Despliegue de K3s en Azure utilizando GitLab CI

En este tutorial, te mostraré cómo desplegar una máquina virtual en Azure e instalar K3s utilizando GitLab CI. Siguiendo estos pasos, podrás automatizar el proceso de creación e instalación de tu clúster K3s en la nube.

Prerrequisitos

Antes de comenzar, asegúrate de tener lo siguiente:

Una cuenta de Azure con los permisos necesarios para crear recursos.
Una cuenta de GitLab con un proyecto configurado.
Las siguientes variables de entorno configuradas en GitLab CI:
- ARM_CLIENT_ID
- ARM_CLIENT_SECRET
- ARM_SUBSCRIPTION_ID
- ARM_TENANT_ID
- GITLAB_ACCESS_TOKEN
- SSH_PRIVATE_KEY
- SSH_PUBLIC_KEY

Estructura del proyecto

El proyecto que vamos a utilizar tiene la siguiente estructura de archivos:

labs-k3s-azure-example-main/
├── .gitlab-ci.yml
├── CHANGELOG
├── Config/
├── Iac/
├── LICENSE
├── README.md
└── Requirements/

Puedes encontrar el código completo en el repositorio de GitLab.

Descripción del pipeline principal

El archivo principal .gitlab-ci.yml define el flujo de trabajo del pipeline CI/CD y utiliza tres archivos secundarios para gestionar las etapas de despliegue, configuración y requisitos del clúster.

Contenido del archivo .gitlab-ci.yml :

variables:
  IAC_PIPELINE_FILE: "Iac/.gitlab-ci-iac.yml"
  CONFIG_PIPELINE_FILE: "Config/.gitlab-ci-config.yml"
  REQUIREMENTS_PIPELINE_FILE: "Requirements/.gitlab-ci-requirements.yml"

stages:
  - deploy
  - config
  - requirements

iac:
  stage: deploy
  variables:
    TF_VAR_ssh_public_key: $SSH_PUBLIC_KEY
  trigger:
    include: 
      - local: $IAC_PIPELINE_FILE
  when: manual

config:
  stage: config
  variables:
    PUBLIC_IP: "40.66.43.154"
    ANSIBLE_USER: "goliat"
    ANSIBLE_HOST: "40.66.43.154"
  trigger:
    include: 
      - local: $CONFIG_PIPELINE_FILE
    strategy: depend
  when: manual

requirements:
  stage: requirements
  variables:
    K8S_AGENT_CONTEXT: "danieljsaldana/k3s-azure-example:goliat"    
    KUBERNETES_NAMESPACE: "k3s"
  trigger:
    include:
      - local: $REQUIREMENTS_PIPELINE_FILE
    strategy: depend
  when: manual

Este archivo define tres etapas (deploy, config, requirements) y utiliza tres archivos secundarios para manejar los detalles específicos de cada etapa. Cada etapa se ejecuta manualmente para proporcionar un mayor control sobre el despliegue.

Configuración de las variables

Se deben realizar unos ajustes en las variables, definiendo la IP de la máquina una vez generada PUBLIC_IP y el ANSIBLE_USER definido en el archivo terraform.tfvars.
También se debe ajustar la variable K8S_AGENT_CONTEXT con el nombre del agente de GitLab CI que se debe conectar al clúster de Kubernetes, seguido del nombre del repositorio.

Descripción de los pipelines secundarios

Pipeline de infraestructura como código (IaC)

El archivo Iac/.gitlab-ci-iac.yml se encarga de la etapa de despliegue de infraestructura utilizando Terraform.

Contenido del archivo Iac/.gitlab-ci-iac.yml :

include:
  - component: gitlab.com/components/opentofu/full-pipeline@~latest
    inputs:
      version: latest
      opentofu_version: 1.7.2
      root_dir: Iac/
      state_name: k3s

stages: [validate, test, build, deploy, cleanup]

variables:
  TF_VAR_ssh_public_key: $SSH_PUBLIC_KEY

before_script:
  - echo "$SSH_PUBLIC_KEY" > Iac/ssh_key.pub
  - chmod 644 Iac/ssh_key.pub

Este archivo incluye un componente de OpenTofu para ejecutar un pipeline completo que pasa por las etapas de validación, prueba, construcción, despliegue y limpieza. Configura la variable TF_VAR_ssh_public_key necesaria para el despliegue de Terraform.

Otros archivos importantes en la carpeta `Iac/`

main.tf : Define los recursos principales de la infraestructura en Azure.
variables.tf : Define las variables necesarias para Terraform.
terraform.tfvars : Define los valores específicos de las variables.

Una vez que se ha completado la etapa de despliegue, se podra acceder al Terraform State en el propio GitLab en la sección Operate > Terraform States.

Pipeline de configuración

El archivo Config/.gitlab-ci-config.yml se encarga de la configuración de la máquina virtual utilizando Ansible.

Contenido del archivo Config/.gitlab-ci-config.yml :

stages:
  - deploy

variables:
  ANSIBLE_HOST_KEY_CHECKING: "False"
  ANSIBLE_USER: $ANSIBLE_USER
  ANSIBLE_HOST: $ANSIBLE_HOST
  PUBLIC_IP: $PUBLIC_IP
  SSH_PRIVATE_KEY: $SSH_PRIVATE_KEY

before_script:
  - mkdir -p ~/.ssh
  - echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
  - chmod 600 ~/.ssh/id_rsa

deploy_ansible:
  image: uhligit/ansible:latest
  stage: deploy
  when: manual
  script:
    - ansible-playbook -i "$ANSIBLE_HOST," Config/playbook.yml -u $ANSIBLE_USER -e "public_ip=$PUBLIC_IP"

Este archivo define una etapa que ejecuta un playbook de Ansible para configurar K3s con TLS SANs.

Otros archivos importantes en la carpeta `Config/`

inventory.ini : Define el inventario de hosts para Ansible.
playbook.yml : Contiene el playbook de Ansible para configurar K3s con TLS SANs.

Pipeline de requisitos

El archivo Requirements/.gitlab-ci-requirements.yml se encarga de instalar K3s en la máquina virtual.

Contenido del archivo Requirements/.gitlab-ci-requirements.yml :

image: 
  name: bitnami/kubectl:latest
  entrypoint: [""]

stages:
  - deploy

deploy_ingress:
  stage: deploy
  script:
    - kubectl config get-contexts
    - kubectl config use-context $K8S_AGENT_CONTEXT
    - kubectl apply -f Requirements/ingress/

deploy_argocd:
  stage: deploy
  script:
    - kubectl config get-contexts
    - kubectl config use-context $K8S_AGENT_CONTEXT
    - |
      if ! kubectl get namespace argocd > /dev/null 2>&1; then
        kubectl create namespace argocd
        kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
      else
        echo "Namespace 'argocd' already exists and ArgoCD is already installed."
      fi

deploy_cert_manager:
  image:
    name: dtzar/helm-kubectl:latest
    entrypoint: [""]
  stage: deploy
  script:
    - kubectl config get-contexts
    - kubectl config use-context $K8S_AGENT_CONTEXT
    - helm version
    - helm repo add jetstack https://charts.jetstack.io --force-update
    - helm repo update
    - |
      if ! helm ls -n cert-manager | grep -q cert-manager; then
        helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.15.1 --set crds.enabled=true
        kubectl apply -f Requirements/clusterIssuer/
      else
        echo "cert-manager is already installed."
      fi

Este archivo define varias etapas para desplegar componentes clave en el clúster K3s, incluyendo ingress, ArgoCD y cert-manager.

Despliegue de Ingress

Configura y despliega los controladores de ingress necesarios en el clúster.

Despliegue de ArgoCD

Despliega ArgoCD en el clúster K3s si no está ya instalado.

Despliegue de Cert-manager

Despliega cert-manager y configura el emisor de certificados.

Configuración de variables de entorno en GitLab CI

Para que el pipeline funcione correctamente, es necesario configurar las siguientes variables de entorno en GitLab CI:

Ve a tu proyecto en GitLab.
Dirígete a Settings > CI / CD > Variables.
Agrega las siguientes variables:

Variable	Valor	Entorno	Máscara	Expander	Protegido
`ARM_CLIENT_ID`	`*****`	Todos (por defecto)	Sí	Sí
`ARM_CLIENT_SECRET`	`*****`	Todos (por defecto)	Sí	Sí
`ARM_SUBSCRIPTION_ID`	`*****`	Todos (por defecto)	Sí	Sí
`ARM_TENANT_ID`	`*****`	Todos (por defecto)	Sí	Sí
`GITLAB_ACCESS_TOKEN`	`*****`	Todos (por defecto)	Sí	Sí
`SSH_PRIVATE_KEY`	`*****`	Todos (por defecto)		Sí	Sí
`SSH_PUBLIC_KEY`	`*****`	Todos (por defecto)		Sí	Sí

Despliegue del pipeline

Etapa de despliegue (deploy):
Etapa de configuración (config):

resource_group_name = "rg-k3s"
location = "francecentral"
vnet_name = "k3s-vnet"
vnet_address_space = ["10.0.0.0/16"]
subnet_name = "k3s-subnet"
subnet_address_prefix = ["10.0.1.0/24"]
nsg_name = "k3s"
vm_name = "k3s"
vm_size = "Standard_B2s"
admin_username = "k3s"
k3s_install_command = "curl -sfL https://get.k3s.io | sh - && sudo k3s kubectl get node"
tags = {
  environment = "k3s"
}

Etapa de requisitos (requirements):
- Esta etapa se encarga de instalar K3s en la máquina virtual y desplegar componentes adicionales como ingress, ArgoCD y cert-manager.
- Los scripts necesarios para la instalación de K3s y la configuración de los componentes adicionales se encuentran en Requirements/.gitlab-ci-requirements.yml.

Conexión del clúster de Kubernetes con GitLab CI

Para conectar el clúster de Kubernetes con GitLab CI, sigue estos pasos:

Ve a tu proyecto en GitLab.
Dirígete a Operate > Cluster de Kubernetes > Connect a cluster.
Escribe el nombre de tu clúster y pulsa en el botón Registrar.
Nos generara un codigo para instalar el agente usando Helm.
Copia el comando y ejecútalo en tu terminal.

Una vez conectado, podrás desplegar tus aplicaciones en el clúster de Kubernetes utilizando GitLab CI.