Edit

TLS configuration - Using your own certificate management (customer managed or BYOC)

Use this article when you want to manage certificates for Azure Monitor pipeline receivers yourself. For the automated option, see Using automated certificate management.

Advantages of BYOC:

  • Replace the default collector server certificate with your own
  • Provide your own CA for client certificate validation
  • Integrate with Azure Key Vault for certificate storage

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.

Configure cert-manager with external PKI

The following example uses Let's Encrypt, but you can use any supported external PKI.

Create issuer resource for external PKI

Save the following YAML to a file named external-pki-issuer.yaml.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: external-pki-issuer
  namespace: pipeline
spec:
  acme:
    # You must replace this email address with your own.
    # Let's Encrypt will use this to contact you about expiring
    # certificates, and issues related to your account.
    email: user@contoso.com
    # If the ACME server supports profiles, you can specify the profile name here.
    # See #acme-certificate-profiles below.
    profile: tlsserver
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      # Secret resource that will be used to store the account's private key.
      # This is your identity with your ACME provider. Any secret name may be
      # chosen. It will be populated with data automatically, so generally
      # nothing further needs to be done with the secret. If you lose this
      # identity/secret, you will be able to generate a new one and generate
      # certificates for any/all domains managed using your previous account,
      # but you will be unable to revoke any certificates generated using that
      # previous account.
      name: example-issuer-account-key
    # Add a single challenge solver, HTTP01 using nginx
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx

Apply the YAML to your cluster by using the following command.

kubectl apply -f external-pki-issuer.yaml

Create certificate resource

Save the following YAML to a file named azmonpipeline-server-cert.yaml.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: azmonpipeline-server-cert
  namespace: pipeline
spec:
  secretName: collector-server-tls
  issuerRef:
    name: external-pki-issuer
  commonName: azmonpipeline-receiver.pipeline.svc.cluster.local
  dnsNames: azmonpipeline-receiver.pipeline.svc.cluster.local

Apply the YAML to your cluster by using the following command. cert-manager adds the certificate and key to the collector-server-tls secret.

kubectl apply -f azmonpipeline-server-cert.yaml

BYOC server certificate requirements

When you bring your own server certificate:

  • Certificate and Private Key: Provide both together.
  • DNS Subject Alternative Names (SANs): The certificate must include appropriate SANs that match the service endpoints.

Important

Azure Monitor pipeline only supports PEM format. All certificates and keys must be converted to PEM before use.

The server certificate must include the service FQDN at minimum:

<pipeline-name>-service.<namespace>.svc.cluster.local

Optionally, include shorter variants for flexibility:

<pipeline-name>-service.<namespace>.svc
<pipeline-name>-service.<namespace>
<pipeline-name>-service

Example:

For a pipeline named byoc-pipeline in the production namespace, the certificate must include:

DNS SANs:
  - byoc-pipeline-service.production.svc.cluster.local
  - byoc-pipeline-service.production.svc (optional)
  - byoc-pipeline-service.production (optional)
  - byoc-pipeline-service (optional)

Certificate storage

Store certificates and keys in Kubernetes resources in the same namespace as the pipeline group:

  • Certificates: Store in Secrets or ConfigMaps
  • Private keys: Store in Secrets only (for security)

Configure TLS or mTLS

Create Kubernetes secrets

To provide your own certificate and key for the client or the pipeline, store them in a Kubernetes secret. Ensure that the following secrets exist in the pipeline namespace so the ARM template can reference them directly.

  • Kubernetes TLS secret named collector-server-tls containing tls.crt and tls.key for the collector
  • Opaque secret named byoc-client-root-ca-secret that stores ca.crt
kubectl create secret tls my-tls-secret --cert=tls.crt --key=tls.key -n <namespace>

You can optionally use the Secret Store Extension (SSE) to automatically synchronize certificates from Azure Key Vault to Kubernetes secrets.

To encrypt Secrets at rest, see Update the key vault mode for an Azure Kubernetes Service (AKS) cluster.

Configure pipeline

Use one of the following templates to configure TLS or mTLS for your Azure Monitor pipeline receivers. Before you deploy the template, update the tlsConfigurations section to match your requirements.

  • Set name to a friendly identifier, such as byoc-mtls, and reference that identifier from any receiver in the tlsConfiguration field.
  • If the receiver omits tlsConfiguration, it uses the platform's default TLS chain created during bootstrap, which covers server-side encryption only.
  • Receivers can share the same TLS configuration, or you can define multiple entries and map each receiver to the appropriate configuration.
  • For BYOC, specify Kubernetes secrets or ConfigMaps for tlsCertificate and clientCa and specify the correct key for subLocation (tls.crt, tls.key, ca.crt).
  • Specify one of the following values for mode:
    • serverOnly: Encrypted transport only, no client authentication.
    • mutualTls: Clients must present certificates.
    • disabled: TLS is not required and all TLS material is cleared
{
  "type": "Microsoft.Monitor/pipelineGroups",
  "apiVersion": "2026-04-01",
  "name": "byoc-cm-pipeline-arm",
  "location": "eastus2",
  "properties": {
    "receivers": [
      {
        "name": "syslog",
        "type": "Syslog",
        "tlsConfiguration": "byoc-mtls",
        "syslog": { "endpoint": "0.0.0.0:514" }
      }
    ],
    "tlsConfigurations": [
      {
        "name": "byoc-mtls",
        "mode": "mutualTls",
        "tlsCertificate": {
          "certificate": {
            "type": "kubernetesSecret",
            "location": "collector-server-tls",
            "subLocation": "tls.crt"
          },
          "privateKey": {
            "type": "kubernetesSecret",
            "location": "collector-server-tls",
            "subLocation": "tls.key"
          }
        },
        "clientCa": {
          "type": "kubernetesSecret",
          "location": "byoc-client-root-ca-secret",
          "subLocation": "ca.crt"
        }
      }
    ]
  }
}

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 modes:

  • mutualTls (default): Full mTLS with both server and client certificate authentication.
  • serverOnly: TLS encryption without client certificate validation.
  • disabled: Plain text communication.

BYOC TLS: Enables TLS by using customer-managed certificates.

{
  "name": "byoc-server-tls",
  "mode": "serverOnly",
  "tlsCertificate": {
    "certificate": {
      "type": "kubernetesSecret",
      "location": "collector-server-tls",
      "subLocation": "tls.crt"
    },
    "privateKey": {
      "type": "kubernetesSecret",
      "location": "collector-server-tls",
      "subLocation": "tls.key"
    }
  }
}

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

{
  "name": "default-server-byoc-client",
  "clientCA": {
    "type": "kubernetesSecret",
    "location": "custom-client-root-ca",
    "subLocation": "ca.crt"
  }
}

BYOC (TLS + mTLS): Enables TLS and mTLS by using customer-managed certificates.

{
  "name": "byoc-mtls",
  "mode": "mutualTls",
  "tlsCertificate": {
    "certificate": {
      "type": "kubernetesSecret",
      "location": "collector-server-tls",
      "subLocation": "tls.crt"
    },
    "privateKey": {
      "type": "kubernetesSecret",
      "location": "collector-server-tls",
      "subLocation": "tls.key"
    }
  },
  "clientCA": {
    "type": "kubernetesSecret",
    "location": "byoc-client-root-ca-secret",
    "subLocation": "ca.crt"
  }
}
  • Last updated on