kubernetes

README

Unikorn Kubernetes Service

Overview

Resources

Unikorn Kubernetes service abstracts away installation of Cluster API.

There are two resource types:

• Cluster Managers, that basically are instances of Cluster API that live in Projects provided by Unikorn Identity.
• Clusters, are Kubernetes clusters, and managed by cluster managers.

Cluster managers are actually contained themselves in virtual clusters, this allows horizontal scaling and multi-tenant separation.

Services

Unikorn is split up into domain specific micro-services:

• Cluster manager and cluster controllers. These are reactive services that watch for resource changes, then reconcile reality against the requested state.
• Server is a RESTful interface that manages Unikorn resource types. As it's intended as a public API e.g. for Terraform or a user interface, it integrates authn/authz functionality too.
• Monitor is a daemon that periodically polls Unikorn resource types, and provides functionality that cannot be triggered by reactive controllers. Most notably, this includes automatic upgrades.

Installation

Unikorn Prerequisites

The use the Kubernetes service you first need to install:

• The identity service to provide API authentication and authorization.
• The region service to provide provider agnostic cloud services (e.g. images, flavors and identity management).

Installing the Service

Is all done via Helm, which means we can also deploy using ArgoCD. As this is a private repository, we're keeping the charts private for now also, so you'll need to either checkout the correct branch for a local Helm installation, or imbue Argo with an access token to get access to the repository.

Installing ArgoCD

ArgoCD is a required to use Unikorn.

Deploy Argo using Helm (the release name is hard coded, don't change it yet please):

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
helm install argocd argo/argo-cd -n argocd --create-namespace

Installing Prerequisites

The Unikorn server component has a couple prerequisites that are required for correct functionality. If not installing server you can skip to the next section.

You'll need to install:

• cert-manager (used to generate keying material for JWE/JWS and for ingress TLS)
• nginx-ingress (to perform routing, avoiding CORS, and TLS termination)

Helm

helm repo add jetstack https://charts.jetstack.io
helm repo add nginx https://helm.nginx.com/stable
helm repo update
helm install cert-manager jetstack/cert-manager -n cert-manager --create-namespace
helm install nginx-ingress nginx/nginx-ingress -n nginx-ingress --create-namespace --set controller.ingressClassResource.default=true

ArgoCD

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cert-manager
  namespace: argocd
spec:
  project: default
  source:
    chart: cert-manager
    helm:
      parameters:
      - name: installCRDs
        value: "true"
      releaseName: cert-manager
    repoURL: https://charts.jetstack.io
    targetRevision: v1.10.1
  destination:
    name: in-cluster
    namespace: cert-manager
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-ingress
  namespace: argocd
spec:
  project: default
  source:
    chart: nginx-ingress
    helm:
      parameters:
      - name: controller.service.httpPort.enable
        value: "false"
      releaseName: nginx-ingress
    repoURL: https://helm.nginx.com/stable
    targetRevision: 0.16.1
  destination:
    name: in-cluster
    namespace: nginx-ingress
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Installing the Kubernetes Service

Helm

Create a values.yaml for the server component: A typical values.yaml that uses cert-manager and ACME, and external DNS could look like:

server:
  ingress:
    host: unikorn.unikorn-cloud.org
    clusterIssuer: letsencrypt-production
    externalDns: true
  oidc:
    issuer: https://identity.unikorn-cloud.org

helm install unikorn charts/unikorn --namespace unikorn --create-namespace --values values.yaml

ArgoCD

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: unikorn
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://unikorn-cloud.github.io/unikorn
    chart: unikorn
    targetRevision: v0.1.8
  destination:
    namespace: unikorn
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Configuring Service Authentication and Authorization

The Unikorn Identity Service describes how to configure a service organization, groups and role mappings for services that require them.

This service requires asynchronous access to the Unikorn Region API in order to poll cloud identity and physical network status during cluster creation, and delete those resources on cluster deletion.

This service defines the unikorn-kubernetes user that will need to be added to a group in the service organization. It will need the built in role infra-manager-service that allows:

• Read access to the region endpoints to access external networks
• Read/delete access to the identites endpoints to poll and delete cloud identities
• Read/delete access to the physicalnetworks endpoints to poll and delete physical networks

Monitoring & Logging

• Prometheus monitoring can be enabled with the --set monitoring.enabled=true flag.
• OTLP (e.g. Jaeger) tracing can be enabled with the set server.otlpEndpoint=jaeger-collector.default:4318 flag.

See the monitoring & logging documentation from more information on configuring those services in the first instance..

Documentation

API (Unikorn Server)

Consult the server API documentation to get started.

Development

Consult the developer documentation for local development instructions.

The architecture documentation details how it all works, and the design considerations.