Skip to main content
Version: 1.13

Custom Domain Names for your Applications
ScaleEnterpriseSelf-Hosted

By default, an application deployed in Okteto will be available at its Okteto subdomain, which has the form *-<okteto-namespace>.<okteto-subdomain>.

For example, an application called hello deployed in the namespace cindylopez will be available at https://hello-cindylopez.example.com on Okteto.

To make your applications available on a non-Okteto subdomain (for example: myapp.com), you can add a custom domain to your Okteto namespace.

Applications that use custom domains will automatically get issued a valid certificate, just like regular Okteto endpoints.

Okteto does not provide a domain registration service (for registering a custom domain name) or a DNS provider service.

Add a Custom Domain Name to your Application.​

Perform the following tasks to use your custom domain in an Okteto Namespace:

  1. Update your DNS configuration so your custom domain points to the Okteto subdomain.

  2. Execute the following commands in the namespace you are configuring with custom domains:

kubectl label ns <okteto-namespace> dev.okteto.com/custom-domain=true --overwrite
kubectl annotate ns $ns dev.okteto.com/domain=<your-custom-domain> --overwrite

and create the following Issuer in your namespace:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: okteto-http01
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: <your-email>
    preferredChain: ""
    privateKeySecretRef:
      name: okteto-http01
    solvers:
    - http01:
       ingress:
         class: nginx
         serviceType: ClusterIP

Configure your Application to use your Custom Domain​

Once your domain has been registered with Okteto, it's time to put it to use.

If you're using Okteto's auto-ingress or generate the host features, then there's nothing to change. Just redeploy your application, and it will automatically pick up your custom domain.

For example, if your application's endpoint was https://hello-cindylopez.okteto.example.com and you added the custom domain myapp.com, after redeployment your application's endpoint will be https://hello.myapp.com.

Using your Root Domain​

If you want to make your application available in the root domain you provided, you'll need to make a small change to your manifests.

If you're using Okteto's auto-ingress features, change the value of the dev.okteto.com/auto-ingress annotation in your service to the word domain, as shown below:

apiVersion: v1
kind: Service
metadata:
  name: hello-service
  annotations:
    dev.okteto.com/auto-ingress: "domain"
spec:
  type: ClusterIP
  ports:
  - name: "hello-world"
    port: 8080
  selector:
    app: hello-world

If you're creating your own ingress, change the value of the dev.okteto.com/generate-host annotation in your ingress to the word domain, as shown below:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello-ingress
  annotations:
    dev.okteto.com/generate-host: "domain"
spec:
  rules:
  - http:
      paths:
      - backend:
          serviceName: hello-world
          servicePort: 8080

If you deployment is powered by Docker Compose, add a label to the service you want to configure a custom domain as shown below:

services:
  fastapi:
    build: .
    replicas: 1
    ports:
      - 8080:8080
    environment:
      - DB_HOST=postgres://pguser:pgpass@postgres:5432/pgdb
      - secret=dev
    labels:
      dev.okteto.com/auto-ingress: "domain"
  postgresql:
    image: bitnami/postgresql:latest
    ports:
      - 5432
    environment:
      - POSTGRES_USER=pguser
      - POSTGRES_PASSWORD=pgpass
      - POSTGRES_DB=pgdb
    volumes:
      - data:/bitnami/postgresql
volumes:
  data:

Okteto will automatically generate the correct host at deploy time. For example, if you added the custom domain myapp.com to your namespace, the ingress will be created with myapp.com as the host.

$ kubectl get ingress custom-dns
NAME         HOSTS          ADDRESS                                                     PORTS     AGE
custom-dns   myapp.com      104.155.138.215,104.197.238.82,104.198.241.5,35.224.92.98   80, 443   169m

We recommend you use this approach instead of hardcoding the hostname in your manifests to keep them portable across namespaces.

Configure your DNS​

In order to use your custom domain in Okteto, you'll need to point your custom DNS to <okteto-namespace>.<okteto-subdoamin>.

You usually configure a CNAME record with your DNS provider to point to it. We recommend you add a wildcard entry so you don't need to create an entry for every service deployed:

RecordNameTarget
CNAME*.myapp.comcindylopez.okteto.example.com
CNAMEmyapp.comcindylopez.okteto.example.com

Consult your DNS provider's documentation for specific instructions on creating CNAME records.

You can confirm your DNS is configured correctly with the host command, assuming your DNS changes have propagated:

$ host hello.myapp.com
hello.myapp.com is an alias for cindylopez.okteto.example.com.
cindylopez.okteto.example.com has address ...