Skip to content

Getting Started with the Certificates Service

This guide will show you how to automatically secure your applications with trusted TLS certificates. The process is fully automated, combining the Service Proxy with the Certificates service to handle everything from domain validation to certificate renewal.

The Automated Workflow

The platform provides a seamless, "zero-touch" experience for certificate management. Because the Certificates service is integrated with our DNS infrastructure, the entire process is automated:

  1. You declare that you want a secure endpoint by defining a hostname in an HTTPProxy resource.
  2. Our DNS service automatically creates the required DNS records for that hostname (if it authority for the domain).
  3. The Certificates service detects the request, validates domain ownership using the DNS records, and issues a trusted TLS certificate from Let's Encrypt.
  4. The certificate is stored as a Kubernetes Secret and automatically attached to the Service Proxy to enable HTTPS.
  5. The certificate is automatically renewed well before it expires.

Exposing an Application with HTTPS

The only step you need to take is to create an HTTPProxy resource that defines the desired hostname for your application. The system handles the rest.

Example

Let's say you have an application running in a Service named my-app-service on port 8080, and you want to expose it securely at app.example.com.

Create the following HTTPProxy resource:

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: my-app-proxy
  namespace: your-namespace
  annotations:
    # This annotation tells the Certificates service which issuer to use.
    # We provide pre-configured issuers for Let's Encrypt.
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  virtualhost:
    fqdn: app.example.com
    tls:
      # The service will create this secret and store the certificate in it.
      secretName: my-app-tls-secret
  routes:
    - services:
        - name: my-app-service
          port: 8080

Key Fields Explained

  • metadata.annotations.cert-manager.io/cluster-issuer: This annotation is the trigger that tells the Certificates service to manage a certificate for this host. We provide letsencrypt-prod for production certificates and letsencrypt-staging for testing.
  • spec.virtualhost.fqdn: The fully qualified domain name (FQDN) that your application will be served from. Our DNS service will automatically create a record for this name pointing to the Service Proxy.
  • spec.virtualhost.tls.secretName: The name of the Kubernetes Secret where the issued TLS certificate and private key will be stored. The Service Proxy will automatically use this secret to terminate TLS.

Once you commit and push this resource to your GitOps repository, the automated workflow will begin. Within a few minutes, your application will be accessible via https://app.example.com with a valid TLS certificate.

Verifying the Certificate Status

You can monitor the status of the certificate issuance process by describing the Certificate resource that the service creates automatically. The resource will have the same name as the secretName you specified.

kubectl describe certificate my-app-tls-secret -n your-namespace

Look for a Condition of Type: Ready and Status: True. This indicates that the certificate has been successfully issued and is ready for use.

Next Steps