Kubernetes Gateways
Last modified on October 4, 2023
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.
Log in to the StrongDM Admin UI.
Select Network > Gateways in the navigation.
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.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 throughbase64
.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.
Follow the steps to create a gateway token.
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) orexternalIPs
in the NodePort section.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
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.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.
Kubernetes Gateway Status in Admin UI
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.
Follow the steps to create a gateway token. You need this token in step 4.
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
To obtain the chart deployment files, clone the StrongDM charts repository. You need to complete this for the next step.
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.
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.
Parameter | Required | Default | Description |
---|---|---|---|
.global.gateway.enabled | Optional | false | Default value is used for relay deployments; set to true for gateways and to enable incoming traffic when using a gateway token |
.global.gateway.service.type | Required | NodePort | Determines the kind of service to run for the gateway, for example NodePort or Loadbalancer |
.global.gateway.service.port | Required | 30001 | Indicates the port the service listens on; if using NodePort , can be different than the port set in the Admin UI |
.global.gateway.service.nodePort | Optional | 30001 | Matches the port value in the Admin UI when the service is set to NodePort |
.global.gateway.service.loadBalancerIP | Optional | None | Assigns the IP address of an existing load balancer when the service is set to LoadBalancer |
.global.secret.token | Required | None | Includes the Base64-encoded value of the relay or gateway token generated in the Admin UI |
.global.deployment.repository | Required | quay.io/sdmrepo/relay | Identifies the location to pull the image for the StrongDM gateway or relay; this can be any repository or a local image (for example, sdm-custom-image:latest ) |
.global.deployment.tag | Required | latest | Assigns tags for the image used for the StrongDM gateway or relay |
.global.deployment.imagePullPolicy | Required | Always | Shows the policy for pulling a new image from the repo |
.global.extraEnvironmentVars | Optional | None | Injects extra environment variables in the format key:value if populated |
.configmap.SDM_ORCHESTRATOR_PROBES | Optional | 9090 | Shows port for a liveliness probe of the gateway or relay |
.configmap.SDM_DOCKERIZED | Optional | true | Sends logs automatically to STDOUT when set to true , overriding settings in the Admin UI |
.configmap.SDM_RELAY_LOG_FORMAT | Optional | json | Determines format for logs when stored locally |
.configmap.SDM_RELAY_LOG_STORAGE | Optional | stdout | Determines where StrongDM Activities are stored |
.configmap.SDM_RELAY_LOG_ENCRYPTION | Optional | plaintext | Changes the encryption of logs |
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 runhelm status <RELEASE_NAME>
to confirm the status of the deployment.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
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>