Certificate Management

Approaches for Certificate Management with varying installs/CNAMEs.

Shipa allows you to have granular control of your CNAME's. This documentation is designed for Certificate Management with the Self-Managed Shipa API which can be ported to your applications.

Use Let's Encrypt Certificate for Shipa API CNAME(s)

For using a Self-Managed Shipa control plane, you may wish to expose your API such that you can connect the Shipa CLI client or connect to Shipa APIs from multiple contexts. This can be achieved by adding a proxy in front of the API that will serve up a trusted cert. If you are exposing your API endpoint publicly, you can leverage the existing ingress controller and cert-manager cluster issuer resources that are installed by default with a Shipa installation by creating an ingress for your API. For example, if you want to expose the Shipa API as target.shipa.my.domain, you could create an ingress rule like this:

apiVersion: networking.k8s.io/v1
kind: Ingress
  name: shipa-api-custom
  namespace: shipa-system
    kubernetes.io/ingress.class: "shipa-nginx-ingress"
    cert-manager.io/cluster-issuer: "shipa-nginx-letsencrypt-issuer"
  - host: target.shipa.my.domain
      - backend:
            name: shipa-api
              number: 8080
        path: /
        pathType: Prefix
  - hosts:
    - target.shipa.my.domain
    secretName: shipa-api-custom-tls

Apply the configuration and re-add your Shipa Target

kubectl apply -f shipa-ingress-cert-issuer.yaml
shipa target add shipa https://my.custom.domain --port 443

Private Shipa Self-Managed API

If you are not exposing your Shipa API publicly, or if you choose to not use Let’s Encrypt for your certificate, then you can still configure a different load balancer or reverse proxy in front of the Shipa API. If you are using a cloud provider and installing the NGINX service with the default type of “LoadBalancer”, you may even be able to install a certificate in the provisioned load balancer, such as an ELB in AWS. With an ELB you would configure the Listener set up for Load Balancer Port 8081 to ensure that it uses “SSL (Secure TCP)” as both the Load Balancer Protocol and the Instance Protocol, and then select an SSL Certificate, which can use AWS Certificate Manager (ACM) to provision a certificate for you. You may need to validate domain ownership with ACM, if you haven’t already, in order for AWS to give you certs for your custom domain, but once that is done you can set your custom domain name to be a CNAME for the DNS Name of the ELB instance.

Static/Existing Load Balancers

If an automatically provisioned load balancer is not an option for you, but you have an existing load balancer, such as A10, F5, or LoadMaster, or a reverse proxy, such as Apache HTTP Server, NGINX, or IIS, then another option for you would be to configure the Shipa NGINX service to be installed as a NodePort type service. To do so you can provide settings to the helm command for service.nginx.serviceType and service.nginx.secureApiNodePort, which would make the sample install command look something like:

helm upgrade --install shipa shipa-charts/shipa \
  --set service.nginx.serviceType=NodePort
  --set service.nginx.secureApiNodePort=30081
  --set auth.adminUser=$ADMIN_EMAIL --set auth.adminPassword=$ADMIN_PASSWORD \
  --namespace shipa-system --create-namespace --timeout=1000s --wait

The NodePort value will need to be within the allowed range of values. Once the NGINX service is running and exposed on the specified port on the worker nodes in your Kubernetes cluster, you can configure either Layer 4 or Layer 7 routing traffic to the IP addresses of the worker nodes on the port defined by NodePort. The certificate that you want to be presented would be stored in the load balancer and then TLS would be offloaded, so that the user connecting would only need to establish secure transport with the load balancer.


What’s Next