Edit

TLS configuration - Using automated certificate management

Use this article when you want the Certificate Manager extension to manage certificates for TLS-enabled Azure Monitor pipeline receivers. For the customer-managed option, see Using your own certificate management.

Prerequisites

  • Arc-enabled Kubernetes cluster with Azure Monitor pipeline installed, along with additional components and prerequisites described in Configure Azure Monitor pipeline.
  • Access to kubectl and the Azure CLI for the Arc-enabled cluster context.

How automated certificate management works

The Certificate Manager extension manages certificate lifecycle and rotation for the pipeline. This process includes the following components:

  • Server Certificates: Unique TLS certificates for each collector service.
  • Client CA Certificates: Client CA certificates for mTLS authentication.
  • Cluster Issuer for Client Certificates: Use cluster issuer arc-amp-client-root-ca-cluster-issuer to issue client certificates for mTLS.
  • Trust Bundles: Automatically distributed CA certificates for validation.
  • Zero-Downtime Rotation: Certificates are renewed seamlessly without service interruption.

Certificate lifecycle

The following sections summarize the lifecycle for server and client certificates:

Server leaf certificates:

  • Duration: 48 hours (2 days)
  • Automatic renewal 24 hours before expiration
  • Managed automatically by the pipeline operator

Client certificates:

Clients control the lifetimes of client certificates, but they must meet zero-downtime rotation constraints. The certificate must renew within 2 days.

Recommended configurations:

  • duration: 48h and renewBefore: 24h
  • duration: 72h and renewBefore: 25h
  • duration: 24h and renewBefore: 12h

Note

Use client certificates generated by using this option only for intra-cluster communication with the pipeline, such as by clients running within the same Kubernetes cluster. Don't use these certificates for clients connecting from outside the cluster. External clients should instead connect through a gateway. See Configure a Kubernetes gateway for Azure Monitor pipeline.

Warning

Client certificates that don't renew within 2 days might become invalid when the CA rotates. Always set renewBefore to ensure renewal happens before the CA enters its next incubation period.

Use automated certificate management

When you deploy a pipeline group with default settings, the operator automatically:

  • Creates unique TLS certificates for each collector service.
  • Configures collectors to use managed server certificates.
  • Distributes trust bundles containing server or client CA certificates to labeled namespaces. You must label the client namespace so the server CA certificate ConfigMap is available in that namespace.
  • Enables mTLS with automatic certificate rotation.

Step 1: Deploy pipeline group

Deploy a pipeline group with default TLS settings and mTLS enabled. You don't need to specify a tlsConfigurations section for the default behavior.

Step 2: Get server CA certificate for client validation

Clients need the server CA certificate to validate the collector's TLS certificate. The pipeline operator automatically distributes CA certificates through trust bundles.

Label your client namespace to receive the server trust bundle:

kubectl label namespace <client-namespace> arc-amp-trust-bundle=true

Extract the server CA certificate:

# Get the server CA certificate from the trust bundle
kubectl get configmap arc-amp-trust-bundle \
      -n <client-namespace> \
      -o jsonpath='{.data.ca\.crt}' > server-ca.pem

The trust bundle is automatically updated during certificate rotation, ensuring clients always have valid CA certificates to validate server connections.

Step 3: Create Client Certificate for mTLS

For mutual TLS authentication, intra-cluster clients need their own certificates issued by the managed client CA.

Note

Use the arc-amp-client-root-ca-cluster-issuer ClusterIssuer only to issue client certificates for intra-cluster clients. Don't use certificates from this ClusterIssuer for clients connecting from outside the cluster. External clients should connect through a gateway. For more information, see Configure a Kubernetes gateway for Azure Monitor pipeline.

Create a certificate resource in your namespace with values that meet zero-downtime rotation constraints:

Save the following YAML to a file named client-certificate.yaml:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-client-certificate
  namespace: <client-namespace>
spec:
  secretName: my-client-tls
  issuerRef:
    name: arc-amp-client-root-ca-cluster-issuer
    kind: ClusterIssuer
    group: cert-manager.io
  commonName: my-client
  usages:
    - client auth
  duration: 48h      # Must renew within 2 days to meet rotation constraints
  renewBefore: 24h   # Renews at 24 hours, well before CA rotation
  privateKey:
    algorithm: ECDSA
    size: 256

Apply the certificate:

kubectl apply -f client-certificate.yaml

Wait for cert-manager to issue the certificate (usually within seconds):

kubectl get certificate my-client-certificate -n <client-namespace> -w

Step 4: Extract Client Certificate and Key

After cert-manager issues the certificate, extract the client certificate and private key:

# Extract client certificate
kubectl get secret my-client-tls -n <client-namespace> \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > client-cert.pem

# Extract client private key
kubectl get secret my-client-tls -n <client-namespace> \
  -o jsonpath='{.data.tls\.key}' | base64 -d > client-key.pem

Step 5: Connect with mTLS

Use the extracted certificates to establish an mTLS connection.

Service DNS Names:

Here are the accessible DNS names the pipeline service supports, listed from most specific to least specific:

  • <pipeline-name>-service.<namespace>.svc.cluster.local (fully qualified)
  • <pipeline-name>-service.<namespace>.svc (cross-namespace)
  • <pipeline-name>-service.<namespace> (namespace-qualified)
  • <pipeline-name>-service (within same namespace)

Example configurations

The following section provides example configurations that you can include in the pipeline configuration.

TLS modes

The Azure Monitor pipeline supports three TLS configuration modes:

tlsConfigurations value Description
"mode": "mutualTls" Full mTLS with both server and client certificate authentication (default)
"mode": "serverOnly" TLS encryption without client certificate validation
"mode": "disabled" Plain text communication

After you assign a name to a tlsConfiguration, any TCP-based receiver in the pipeline configuration can reference it. If you don't specify a TLS configuration for a receiver, the receiver defaults to mutualTls mode.

Default TLS: Enables TLS by using automated certificate management.

"tlsConfigurations": [
    {
        "name": "automanaged-server-tls",
        "mode": "serverOnly"
    }
],
"receivers": [
    {
        "type": "Syslog",
        "name": "receiverSyslog",
        "tlsConfiguration": "automanaged-server-tls",
          ....
    }
]

Default TLS + BYOC mTLS: Enables TLS by using automated certificate management and mTLS client authentication by using customer-managed certificates.

"tlsConfigurations": [
    {
      "name": "automanaged-server-byoc-client",
      "clientCA": {
        "type": "kubernetesSecret",
        "location": "custom-client-root-ca",
        "subLocation": "ca.crt"
      }
    }
],
"receivers": [
    {
        "type": "Syslog",
        "name": "receiverSyslog",
        "tlsConfiguration": "automanaged-server-byoc-client",
          ....
    }
]
  • Last updated on