Skip to main content

Configure External Access & TLS

After deploying vCluster.Pro, you may want to be able to access the deployment via a routable IP address or a resolvable domain name. You may also wish to secure the deployment with a TLS certificate. This is of course extra useful for sharing vCluster.Pro access with other members of your team who may or may not have direct access to Kubernetes!

Requirements

Getting vCluster.Pro set up to be accessed via routable IP or domain name, and to be secured via TLS requires the cluster that vCluster.Pro is deployed in to have an available load balancer or ingress controller, appropriate DNS settings to be in place, and some mechanism for assigning TLS certificates (i.e. cert-manager).

External Access​

vCluster.Pro, like any other service in Kubernetes, can be exposed in a few ways -- in this section we'll outline how to expose vCluster.Pro via an ingress controller (nginx ingress controller in this example), as well as by a LoadBalancer.

External Access via NGINX Ingress Controller​

Heads up!

This section assumes you already have the nginx ingress controller installed, if you don't, check out the 'Manual Ingress Controller Installation' tab!

  1. Run the command:

    vcluster pro start --host=vcluster-pro.mydomain.tld
    Update the Domain!

    Make sure you update the hostname in the above command!

  2. Set the $VERSION variable to the vCluster.Pro version you want to upgrade to OR set it to the current version using:

    CHART=$(kubectl get service loft -n vcluster-pro -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  3. To upgrade vCluster.Pro via vCluster.Pro CLI, run:

    vcluster pro start --upgrade --version=$VERSION --values=vcluster-pro.yaml
    Versions and Values

    The $VERSION variable above is an environment variable set to your desired vCluster.Pro version to deploy. The vcluster-pro.yaml file is an optional YAML file that contains Helm values you would like to use when upgrading your vCluster.Pro deployment.

  4. Determine the External-IP address:

    kubectl get ingress -n vcluster-pro
    NAME           CLASS    HOSTS                ADDRESS          PORTS     AGE
    loft-ingress   <none>   vcluster-pro.mydomain.tld    x.x.x.x          80, 443   10m
    Address

    If you never get a valid IP Address in the ADDRESS column shown above, you will need to work with your Kubernetes administrator to ensure your ingress is properly configured!

  5. Set up a DNS A record to the ingress address (x.x.x.x). Make sure vCluster.Pro is reachable at the address, you can check that with curl as shown below, or simply browse to the address in your browser of choice:

    curl https://vcluster-pro.mydomain.tld/version --insecure | jq
    {
      "kind": "Version",
      "apiVersion": "version.loft.sh",
      "metadata": {
        "creationTimestamp": null
      },
      "version": "v3.0.0",
      "major": "3",
      "minor": "0",
      "instance": "",
      "kubeVersion": "v1.24.2",
      "newerVersion": "",
      "shouldUpgrade": false
    }

External Access via LoadBalancer​

    AWS Load Balancers

    If you are using AWS, make sure you are using a Network Load Balancer (NLB) to route traffic, since other load balancers do not support the SPDY protocol Kubernetes requires.

    apiVersion: v1
    kind: Service
    metadata:
      annotations:
        # Make sure to adjust the next line:
        service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:eu-west-2:xxx:certificate/xxx"
        service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
        service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "tcp"
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
      name: vcluster-pro-loadbalancer
      namespace: vcluster-pro
    spec:
      type: LoadBalancer
      ports:
        - name: http
          port: 80
          protocol: TCP
          targetPort: 8080
        - name: https
          port: 443
          protocol: TCP
          targetPort: 10443
      selector:
        app: loft

  2. Create the load balancer with this command:

    kubectl apply -f vcluster-pro-loadbalancer.yaml

  3. Wait until the load balancer receives an External-IP address:

    kubectl get svc vcluster-pro-loadbalancer -n vcluster-pro
    NAME                            TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)          AGE
    vcluster-pro-loadbalancer       LoadBalancer   10.112.2.142    x.x.x.x          443:30933/TCP    3m16s

  4. Make sure vCluster.Pro is reachable at the load balancer's external address, you can check that with curl as shown below, or simply browse to the address in your browser of choice:

    curl https://x.x.x.x/version --insecure | jq
    {
      "kind": "Version",
      "apiVersion": "version.loft.sh",
      "metadata": {
        "creationTimestamp": null
      },
      "version": "v3.0.0",
      "major": "3",
      "minor": "0",
      "instance": "",
      "kubeVersion": "v1.24.2",
      "newerVersion": "",
      "shouldUpgrade": false
    }

Configure TLS​

Cert-Manager​

  1. Install cert-manager to your cluster:

    helm upgrade --install  cert-manager cert-manager  --repository-config=''\
      --namespace cert-manager  --create-namespace \
      --repo https://charts.jetstack.io \
      --set installCRDs=true \
      --wait

  2. Edit your existing vcluster-pro.yaml file, or create a new file named vcluster-pro.yaml with content:

    ingress:
      annotations:
        # Make sure the following line matches the name of your issuer (or use the section below to create one)
        cert-manager.io/cluster-issuer: lets-encrypt-http-issuer
      tls:
        enabled: true
        secret: tls-vcluster-pro

    certIssuer:
      create: true # Change this if you already have your own cert-issuer
      name: lets-encrypt-http-issuer
      email: "YOUR_EMAIL" # REQUIRED
      secretName: vcluster-pro-letsencrypt-credentials
      httpResolver:
        enabled: true
        ingressClass: nginx
      resolvers: []
      server: https://acme-v02.api.letsencrypt.org/directory

  3. Set the $VERSION variable to the vCluster.Pro version you want to upgrade to OR set it to the current version using:

    CHART=$(kubectl get service loft -n vcluster-pro -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  4. Upgrade vCluster.Pro via:

    To upgrade vCluster.Pro via vCluster.Pro CLI, run:

    vcluster pro start --upgrade --version=$VERSION --values=vcluster-pro.yaml

AWS Certificate Manager (ACM)​

  1. Determine the External-IP address of your ingress:

    kubectl get ingress -n vcluster-pro
    NAME           CLASS    HOSTS                ADDRESS          PORTS     AGE
    loft-ingress   <none>   vcluster-pro.mydomain.tld    x.x.x.x          80, 443   10m
                                                 ^^^^^^^

  2. Find the AWS Elastic Load Balancer(ELB) for this IP address in the AWS console

  3. Switch to the tab Listeners

  4. In the column "SSL Certificates", click on the link View/edit certificates

  5. Click on the + Synbol next to the tab Certificates and add your Access Control Manager (ACM) managed certificate to the ingress controller's Load Balancer

Manually Provisioned Certificate​

  1. Create a Kubernetes secret from your certificate:

    kubectl create secret generic tls-vcluster-pro -n vcluster-pro --type=kubernetes.io/tls \
      --from-file=tls.crt=tls.crt \
      --from-file=tls.key=tls.key

  2. Edit your existing vcluster-pro.yaml file, or create a new file named vcluster-pro.yaml with content:

    ingress:
      tls:
        enabled: true
        secret: tls-vcluster-pro # Make sure this matches the name of your cert from the previous step

  3. Set the $VERSION variable to the vCluster.Pro version you want to upgrade to OR set it to the current version using:

    CHART=$(kubectl get service loft -n vcluster-pro -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  4. Upgrade vCluster.Pro via:

    To upgrade vCluster.Pro via vCluster.Pro CLI, run:

    vcluster pro start --upgrade --version=$VERSION --values=vcluster-pro.yaml

Self-Signed Certificate​

  1. Create a new private key:

    openssl genrsa -out tls.key 4096

  2. Create a file named ssl.conf with the following content:

    [ req ]
    default_bits       = 4096
    distinguished_name = req_distinguished_name
    x509_extensions    = v3_ca
    req_extensions     = v3_req
    x509_extensions    = usr_cert

    [ req_distinguished_name ]
    organizationName          = Organization Name (eg, company)
    organizationName_default  = vcluster-pro
    commonName                = Common Name (e.g. server FQDN or YOUR name)
    commonName_default        = vcluster-pro.mydomain.tld

    [ usr_cert ]
    basicConstraints  = CA:FALSE
    nsCertType        = client, server
    keyUsage          = digitalSignature
    extendedKeyUsage  = serverAuth, clientAuth

    [ v3_req ]
    subjectAltName   = @alt_names
    extendedKeyUsage = serverAuth, clientAuth
    basicConstraints = CA:FALSE
    keyUsage         = digitalSignature

    [ alt_names ]
    DNS.1 = localhost

  3. Create a certificate signing request:

    openssl req -new -sha256 \
        -out tls.csr \
        -key tls.key \
        -config ssl.conf

  4. Generate the certificate:

    openssl x509 -req \
        -sha256 \
        -days 3650 \
        -in tls.csr \
        -signkey tls.key \
        -out tls.crt \
        -extensions v3_req \
        -extfile ssl.conf

  5. Create a Kubernetes secret from your certificate:

    kubectl create secret generic tls-vcluster-pro -n vcluster-pro --type=kubernetes.io/tls \
      --from-file=tls.crt=tls.crt \
      --from-file=tls.key=tls.key

  6. Edit your existing vcluster-pro.yaml file, or create a new file named vcluster-pro.yaml with content:

    ingress:
      tls:
        enabled: true
        secret: tls-vcluster-pro # Make sure this matches the name of your cert from the previous step

  7. Set the $VERSION variable to the vCluster.Pro version you want to upgrade to OR set it to the current version using:

    CHART=$(kubectl get service loft -n vcluster-pro -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  8. Upgrade vCluster.Pro via:

    To upgrade vCluster.Pro via vCluster.Pro CLI, run:

    vcluster pro start --upgrade --version=$VERSION --values=vcluster-pro.yaml
Last updated on