Deploy services with mTLS enabled

Available since MKE 3.5.0

Mutual Transport Layer Security (mTLS) is a process of mutual authentication in which both parties verify the identity of the other party, using a signed certificate.

You must have the following items to deploy services with mTLS:

  • One or more CA certificates for signing the server and client certificates and keys.

  • A signed certificate and key for the server

  • A signed certificate and key for the client


To deploy a back-end service with proxy-managed mTLS enabled:

  1. Create a secret for the CA certificate that the client uses to authenticate the server.

  2. Modify the docker-compose.yml file produced in Proxy-managed TLS:

    1. Add the following label to the docker-compose.yml file:

      com.docker.lb.client_ca_cert: demo_app.example.org.client-ca-cert
      
    2. Add the CA certificate to the secrets: in the docker-compose.yml file:

      app.example.org.client-ca.cert:
        file: ./app.example.org.client-ca.cert
      

    The docker-compose-yml file presents as follows:

    version: "3.2"
    
    services:
      demo:
        image: ehazlett/docker-demo
        deploy:
          replicas: 1
          labels:
            com.docker.lb.hosts: app.example.org
            com.docker.lb.network: demo-network
            com.docker.lb.port: 8080
            com.docker.lb.ssl_cert: demo_app.example.org.cert
            com.docker.lb.ssl_key: demo_app.example.org.key
            com.docker.lb.client_ca_cert: demo_app.example.org.client-ca.cert
        environment:
          METADATA: proxy-handles-tls
        networks:
          - demo-network
    
    networks:
      demo-network:
        driver: overlay
    secrets:
      app.example.org.cert:
        file: ./app.example.org.cert
      app.example.org.key:
        file: ./app.example.org.key
      app.example.org.client-ca.cert:
        file: ./app.example.org.client-ca.cert
    
  3. Deploy the service:

    docker stack deploy --compose-file docker-compose.yml demo
    
  4. Test the mTLS-enabled service:

    curl --insecure \
    --resolve app.example.org:<mke-https-port>:<mke-ip-address> \
    --cacert client_ca_cert.pem \
    --cert client_cert.pem \
    --key client_key.pem \
    https://app.example.org:<mke-https-port>/ping
    

    A successful deployment returns a JSON payload in plain text.

    Note

    Omitting --cacert, --cert, or --key from the cURL command returns an error message, as all three parameters are required.