Kubernetes Gateways

Overview #

This installation guide describes how to create a gateway or relay in your Kubernetes cluster. You can follow the manual approach or optionally use the Helm chart method to install your gateway or relay.

Prerequisites #

To be successful when using this guide, you must meet the following general requirements:

• Ensure that you are an Administrator in StrongDM.
• Have a running Kubernetes cluster with publicly accessible nodes and stable IPs.
• Install the kubectl command-line tool to interact with your Kubernetes clusters.
• Obtain a valid StrongDM gateway or relay token.

Create a Gateway Token #

To successfully set up your Kubernetes gateway, you must first create the gateway in the Admin UI and generate a token for it. With a few noted exceptions, the steps to create a relay token are very similar.

1. Log in to the StrongDM Admin UI.

2. Select Network > Gateways in the navigation.

3. Click Add gateway. You can rename the gateway or modify it later. Advertised host should be the IP address or host that the gateway listens on. Select a TCP port (default 5000) for the service to listen on. When using Helm to install the gateway, check the Helm chart configurations for additional port information.

   If you intend to instead create a relay, go to Network > Relays and click Add relay. Add a name and click Create relay. For more information about the differences between gateways and relays, see Nodes.

4. Click Create gateway and the gateway token appears in a modal. Copy the token and set it aside. You need in the following step. See sdm admin relay create-gateway if you want to generate a token via the CLI.

   If you generate the token from the CLI, it may contain a trailing \n character, which you have to remove before passing it through base64.

5. On macOS, encode the resulting token in Base64 using echo -n [token-string] | base64. PowerShell and Windows commands may differ.

Create a Gateway Manually #

Once you have a valid gateway token, you can continue with the steps in this section to manually create your Kubernetes gateway. With a few noted exceptions, the process to add a relay is very similar.

1. Follow the steps to create a gateway token.

2. Create the YAML manifest for your Kubernetes gateway. Use the following content, replacing [token-in-base64] with your Base64-encoded token.

   kind: Secret
   apiVersion: v1
   metadata:
     name: sdm-relay-secret
   type: Opaque
   data:
     token: [token-in-base64]
   ---
   kind: Deployment
   apiVersion: apps/v1
   metadata:
     name: sdm-relay-deployment
     labels:
       app: sdm-relay
   spec:
     replicas: 1 # must always be 1.
     selector:
       matchLabels:
         app: sdm-relay
     template:
       metadata:
         labels:
           app: sdm-relay
       spec:
       # You may use node affinity to ensure that these containers are only
       # deployed to publicly visible nodes.
       # This doesn't work with fargate profiles
       #      affinity:
       #        nodeAffinity:
       #          requiredDuringSchedulingIgnoredDuringExecution:
       #            nodeSelectorTerms:
       #            - matchExpressions:
       #              - key: alpha.eksctl.io/nodegroup-name
       #                operator: In
       #                values:
       #                - ng-1
         containers:
         - name: sdm-relay
           image: quay.io/sdmrepo/relay:latest
           imagePullPolicy: Always
           env:
           - name: SDM_ORCHESTRATOR_PROBES
             value: ":9090"
           - name: SDM_RELAY_TOKEN
             valueFrom:
               secretKeyRef:
                 name: sdm-relay-secret
                 key: token
           livenessProbe:
             httpGet:
               path: /liveness
               port: 9090
             initialDelaySeconds: 25
             timeoutSeconds: 10
             periodSeconds: 15
             failureThreshold: 5
   ---
   

   If you are setting up a relay, that is the end of the config file. If you are setting up a gateway, you also need the next snippet added to your YAML manifest.

   kind: Service
   apiVersion: v1
   metadata:
     name: sdm-relay-service
     labels:
       app: sdm-relay
   spec:
     type: "NodePort"
     selector:
       app: sdm-relay
     ports:
       - name: gateway
         # or relay
         port: 30001
         targetPort: 5000
         nodePort: 30001
         # You may use externalIPs as a way to get a stable IP configuration.
         # then map 80.11.12.10 to sdmrelay.mycompany.com
     externalIPs:
       - 34.220.97.45
   

   To ensure that the external IP address is persistent, you need to either use node affinity (in the Deployment section) or externalIPs in the NodePort section.

3. Create the deployment and activate your gateway. You may have to specify a directory for the YAML file.

   kubectl create -f name-of-gateway-file.yml
   

4. Verify the gateway is running. Your gateway appears in the list of running services.

   kubectl get services
   

   NAME                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)           AGE
   kubernetes          ClusterIP   10.96.0.1       <none>        443/TCP           21h
   sdm-relay-service   NodePort    10.104.132.14   <none>        30001:30001/TCP   21h
   

   Relay deployments are not listed under kubectl services.

5. Log in to the Admin UI. Go to Network > Gateways. The gateway you created appears online with a heartbeat. Click Details to view additional gateway information. Relay status can be verified under Network > Relays.

   

Create a Gateway With Helm #

In your Kubernetes cluster, you may have applications consisting of multiple microservices with slight differences in deployment and service configurations across environments. This could require manual management of separate YAML files for each microservice.

Alternatively, Helm can be used to define a common blueprint that leverages its templating engine to dynamically replace YAML values for your various cluster deployments. As a package manager for Kubernetes, it bundles all YAML files together in a chart, injects YAML values into the chart, and produces valid Kubernetes manifests. Therefore, Helm can give you the flexibility to reuse charts among applications and microservices in Kubernetes.

Helm prerequisites #

If using Helm to install the gateway or relay, you must meet these requirements in addition to the general prerequisites:

• Run a Kubernetes cluster v1.16+.
• Install Helm 3.0+ and Git locally.
• If you are using Nginx Ingress Controller, manually patch your services to allow TCP and UDP traffic.

Important recommendations #

Consider the following recommendations when setting up your gateway or relay using Helm:

• To get a gateway token, you need an external IP address to register. This external address is immutable after creation.
• Tokens cannot be reused between relays or gateways. A recommended ReplicaSet of 1 is set by default to ensure a new gateway or relay is deployed with each chart without causing any token conflicts.
• If you are running multiple StrongDM gateways or relays, we recommend having multiple points of ingress instead of reusing the same ingress address. Using the same address can invalidate the session if traffic is routed to a gateway or relay that did not start the connection. We also suggest using a one-to-one-ratio of load balancers to gateways.

Install the sdm-relay Helm chart #

To leverage the flexibility of Helm, we created charts to deploy your StrongDM gateways or relays across your Kubernetes clusters. For more, see our StrongDM charts repository. You can use the following steps to install a gateway or relay with Helm.

1. Follow the steps to create a gateway token. You need this token in step 4.

2. Add the StrongDM chart repository:

   helm repo add strongdm https://helm.strongdm.com/stable/
   

   The output confirms the chart was added:

   "strongdm" has been added to your repositories
   

3. To obtain the chart deployment files, clone the StrongDM charts repository. You need to complete this for the next step.

4. Go to the cloned local copy of the StrongDM charts repository created in the previous step. It contains a local copy of the sdm-relay values.yaml file that can be used as a template.

5. Open this local values.yaml file to view and configure chart parameters listed in the following table. Make sure to add the Base64-encoded value of the gateway token you generated. Parameters are the same for gateways and relays, with a few noted exceptions.

6. Install the chart archive. Replace <RELEASE_NAME> with a unique and meaningful value to help track package deployments and releases. The value after the -f flag includes the path or URL to your YAML file. To learn more, see the helm install reference documentation.

   helm install <RELEASE_NAME> strongdm/sdm-relay -f myvalues.yaml
   

   NAME: sdm-gateway-070722
   LAST DEPLOYED: Wed Jul  7 18:35:10 2022
   NAMESPACE: default
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   NOTES:
   Thank you for installing sdm-relay using helm.
   
   Your release is named sdm-gateway-070722.
   
   To learn more about the release, try:
   
   helm status sdm-gateway-070722
   helm get all sdm-gateway-070722
   

   You can run helm status <RELEASE_NAME> to confirm the status of the deployment.

7. Confirm the gateway service is running in your cluster:

   kubectl get all
   

   NAME                                                      READY       STATUS          RESTARTS     AGE
   pod/sdm-gateway-070722-deployment-847fcf75f9-c7854        1/1         Running         0            2m44s
   
   NAME                                                      TYPE        CLUSTER-IP      EXTERNAL-IP  PORT(S)          AGE
   service/kubernetes                                        ClusterIP   10.100.0.1      <none>       443/TCP          38h
   service/sdm-gateway-070722-svc                            NodePort    10.100.24.181   <none>       30001:30001/TCP  2m44s
   
   NAME                                                      READY       UP-TO-DATE      AVAILABLE    AGE
   deployment.apps/sdm-gateway-070722-deployment             1/1         1               1            2m44s
   
   NAME                                                      DESIRED     CURRENT         READY        AGE
   replicaset.apps/sdm-gateway-070722-deployment-847fcf75f9  1           1               1            2m44s
   

8. Log in to the Admin UI. Go to Network > Gateways. The gateway you created appears online with a heartbeat. Click Details to view additional gateway information. Relay status can be verified under Network > Relays.

Upgrade the sdm-relay Helm chart #

To upgrade the sdm-relay Helm chart, run the following command. For more, see the helm upgrade command documentation.

helm upgrade <RELEASE_NAME> strongdm/sdm-relay --install

Uninstall the sdm-relay Helm chart #

You can uninstall the sdm-relay Helm chart by running the following command. This command removes all Kubernetes components associated with the release and deletes the release. For more, see the helm uninstall reference documentation.

helm uninstall <RELEASE_NAME>