Deploy on Kubernetes

Introduction

Setting up a document generation solution in your Kubernetes cluster is simple.

You can use Carbone Community feature for free without licence.
To use Carbone Enterprise Edition on Azure, you need a Carbone license. Talk to us to find out more.

Quickstart

Storing Carbone secrets

The first thing is to store the secrets that will be used by Carbone. In this simple example, only the license is needed, but you also need to store the public key if authentication is enabled.

To store the license :

export CARBONE_EE_LICENSE=`cat your-license.carbone-license`

kubectl create secret generic carbone-license --from-literal=license=${CARBONE_EE_LICENSE} 

To check that it has been taken into account:

kubectl get secret

Configuring persistents volumes

Carbone requires persistent storage for templates. If multiple pods are used, render storage is also required.

These volumes must be configured as ReadWriteMany. You therefore need to choose the best implementation for your cloud provider (NFS is often the best solution).

Here is an example of yaml for the generic configuration of this volume:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: carbone-storage
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi

To deploy it on the cluster :

kubectl apply -f carbone-volume.yaml

Pods deployment

Here is an example of a yaml deployment with the creation of 3 Carbone pods:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: carbone-sample-deployment
  labels: 
    name: carbone-ee
spec:
  replicas: 3
  selector:
    matchLabels:
      name: carbone-ee
  template:
    metadata:
      labels:
        name: carbone-ee
    spec:
      containers:
      - name: carbone
        image: "docker.io/carbone/carbone-ee:full"
        resources:
          requests:
            cpu: 1024m
            memory: 2048Mi
        ports:
        - containerPort: 4000
        env:
        - name: CARBONE_EE_STUDIO
          value: "true"
        - name: CARBONE_EE_LICENSE
          valueFrom:
            secretKeyRef:
              name: carbone-license
              key: license
        volumeMounts:
        - mountPath: /app/template
          name: carbone-storage
          subPath: template
        - mountPath: /app/render
          name: carbone-storage
          subPath: render
        livenessProbe:
          httpGet:
            path: /status          # The path to check for the liveness probe
            port: 4000             # The port to check on
          initialDelaySeconds: 15  # Wait this many seconds before starting the probe
          periodSeconds: 5         # Check the probe every 10 seconds
        readinessProbe:
          httpGet:
            path: /status          # The path to check for the readiness probe
            port: 4000             # The port to check on
          initialDelaySeconds: 5   # Wait this many seconds before starting the probe
          periodSeconds: 5         # Check the probe every 5 seconds
      volumes:
      - name: carbone-storage
        persistentVolumeClaim:
          claimName: carbone-storage

To deploy it on the cluster :

kubectl apply -f carbone-simple-deployment.yaml

You can check pods status :

kubectl get pod

Service deployment

The final step is to declare the service for expose it:

kubectl expose deployment carbone-sample-deployment --type=LoadBalancer --name=carbone

You can check pods status :

kubectl get service

The API and Studio Carbone are now available:

http://localhost:4000

Configuration

Authentification

To enable API authentification, you need to follow these steps :

- Set CARBONE_EE_AUTHENTICATION to true

- Generate private/public Carbone Key

The key generation tool is included in the docker image from Carbone version 5 onwards.

docker run -it --platform "linux/amd64" carbone/carbone-ee:slim-5.0.0-beta.0 generate-keys

The two keys will be generated and displayed in the console.

Store content of public key in new kubernetes secret and map it to /app/config/key.pub on all Carbone pods. Create the files key.pem (with private key) and keep it secret on your side.

- Generate JWT token

Follow interactive shell :

docker run -it --platform "linux/amd64" carbone/carbone-ee:slim-5.0.0-beta.0 generate-token

## Paste in terminal content of key.pem

A JWT token is then displayed in the console. You can then use it in your API calls.