How to deploy the Orchestrator

This guide shows you how to deploy the Orchestrator component of Substra.


To deploy the Orchestrator you will need a fully configured Kubernetes cluster. You will also need some tools:

Preparing your Helm values

The orchestrator deployment is packaged using Helm. You can find the complete description of values that can be used to configure the chart on Artifact Hub.

  1. Add the Helm repository for Substra:

    helm repo add substra
  2. Create a Helm values file named orchestrator-values.yaml with the following content:

      enabled: true
      hostname: HOSTNAME
    Replace HOSTNAME with the hostname of your Orchestrator.
    This will setup the ingress to make your Orchestrator accessible at the defined hostname.
  1. Setup your Substra channels. In the orchestrator-values.yaml file, add the following content:

      - name: CHANNEL-NAME
        organizations: [ORG-NAME, ...]
    Replace CHANNEL-NAME with the name you want to give to your channel.
    Replace ORG-NAME, ... with the names of the Organizations that you want to include in this channel.
    If you want more than one channel you can add more items in the list.

Here you have created the configuration required to have a running orchestrator that can support a Substra network. If you want you can jump directly to the section Deploy the Chart. You can also follow along the next sections to enhance the security of your orchestrator.

Setup TLS

In a production environment, we recommend to enable TLS for your orchestrator. For this, you will need to generate a few certificates. Here we will generate them manually but you can also use automated tools for this task. If you want to use automated tools we provide a certificate resource for cert-manager. The orchestrator.tls.createCertificates values should be a good place for you to get started.

The Orchestrator needs to handle SSL termination for this to work. You may need to adapt your proxy configuration to let the traffic go through it. For example if you use ingress-nginx you may want to read the ssl passthrough chapter of their documentation.

To setup TLS, follow these steps:

  1. Enable TLS, in the orchestrator-values.yaml file add the following content:

        enabled: true
  2. Generate a self-signed Certificate Authority:

    1. Create an openssl config file named example-openssl.cnf with the following content:

      [ req ]
      default_bits           = 2048
      default_md             = sha256
      distinguished_name     = req_distinguished_name
      [ req_distinguished_name ]
      [ v3_ca ]
      basicConstraints = critical,CA:TRUE
      subjectKeyIdentifier = hash
      authorityKeyIdentifier = keyid:always,issuer:always
      keyUsage = cRLSign, keyCertSign
    2. Generate a private key for signing certificates:

      openssl genrsa -out orchestrator-ca.key 2048
    1. Generate your Certificate Authority certificate:

      openssl req -new -x509 -days 365 -sha256 -key orchestrator-ca.key -extensions v3_ca -config example-openssl.cnf -subj "/CN=Orchestrator Root CA" -out orchestrator-ca.crt
  3. Generate a certificate for the Orchestrator

    1. Generate a certificate signing request:

      openssl req -newkey rsa:2048 -nodes -keyout orchestrator-tls.key -subj "/CN=HOSTNAME" -out orchestrator-cert.csr
      Replace HOSTNAME with the hostname of your Orchestrator. This should be the same HOSTNAME as in the ingress configuration.

      This will generate a private key for the orchestrator and a certificate signing request. You should have two new files in your current directory orchestrator-tls.key and orchestrator-cert.csr.

    2. Sign the request with the Certificate Authority key:

      openssl x509 -req -days 365 -in orchestrator-cert.csr -CA orchestrator-ca.crt -CAkey orchestrator-ca.key -CAcreateserial -out orchestrator-tls.crt -sha256 -extfile <(printf "subjectAltName=DNS:HOSTNAME")
      Replace HOSTNAME with the hostname of your Orchestrator.


      We don’t recommend having your certificate valid for a year, you should change this value based on your company policy.

    3. Delete the Certificate Signing Request:

      rm orchestrator-cert.csr
  4. Create a Kubernetes ConfigMap for the CA certificate:

    kubectl create configmap orchestrator-tls-cacert --from-file=ca.crt=orchestrator-ca.crt
  5. Create a Kubernetes Secret for the orchestrator TLS key and certificate:

    kubectl create secret tls orchestrator-tls-server-pair --cert=orchestrator-tls.crt --key=orchestrator-tls.key
  6. Optional: If you also want to setup mTLS to authenticate your client follow the guide How to set up mTLS.

Deploy the Chart

To deploy the orchestrator in your Kubernetes cluster follow these steps:

  1. Deploy the Orchestrator Helm chart:

    helm install RELEASE-NAME substra/orchestrator --version VERSION --values orchestrator-values.yaml
    Replace RELEASE-NAME with the name of your orchestrator release (it can be any arbitrary name).
    Replace VERSION with the version of the orchestrator helm chart you want to deploy.

    This will create all the Kubernetes resources required for a functional Orchestrator in your Kubernetes cluster.

  2. Validate that the deployment was successful:

    grpcurl [--cacert orchestrator-ca.crt] HOSTNAME:443 list
    Replace HOSTNAME with the hostname of your orchestrator.
    Add the --cacert argument if you deployed your orchestrator with TLS.

    The output of this command should be the following:

    Failed to list services: rpc error: code = Unknown desc = OE0003: missing or invalid header 'mspid'

    This is expected because the Orchestrator server expects some gRPC headers to be present but we did not provide them. Even if it is an error, since this response is from the server it is sufficient to tell your setup is working.