Kubernetes Nodes

Last modified on May 8, 2024


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


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 Token

To successfully set up your Kubernetes node, you must first create the gateway or relay in the Admin UI and generate a token for it.

To create a gateway token, follow these steps.

  1. Log in to the Admin UI at app.strongdm.com.
  2. Go to Network > Gateways.
  3. Click Add gateway.
  4. For Name, enter a name for the gateway.
  5. For Advertised Host, enter the IP address or host that the gateway listens on.
  6. For Advertised Port, set the port (default 5000) for the service to listen on.
  7. Click Create gateway and the gateway token appears in a modal.
  8. Copy the token and keep it in a secure place.

To create a relay token, follow these steps.

  1. Log in to the Admin UI at app.strongdm.com.
  2. Go to Network > Relays.
  3. Click Add relay.
  4. For Name, enter a name for the relay.
  5. Click Create relay.
  6. Copy the token and keep it in a secure place.

To generate a token via the CLI, see sdm admin relay create-gateway.

On macOS, there is an additional step: encode the resulting token in Base64 using echo -n [token-string] | base64. PowerShell and Windows commands may differ. If you generated the token from the CLI, it may contain a trailing \n character, which you have to remove before passing it through base64.

Create a Node Manually

Once you have a valid token, you can continue with the steps in this section to manually create your Kubernetes gateway or relay.

  1. Follow the steps to create a token.

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

    kind: Secret
    apiVersion: v1
      name: sdm-relay-secret
    type: Opaque
      token: [token-in-base64]
    kind: Deployment
    apiVersion: apps/v1
      name: sdm-relay-deployment
        app: sdm-relay
      replicas: 1 # must always be 1.
          app: sdm-relay
            app: sdm-relay
        # 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
          - name: sdm-relay
            image: public.ecr.aws/strongdm/relay:latest
            imagePullPolicy: Always
            - name: SDM_ORCHESTRATOR_PROBES
              value: ":9090"
            - name: SDM_RELAY_TOKEN
                  name: sdm-relay-secret
                  key: token
                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
      name: sdm-relay-service
        app: sdm-relay
      type: "NodePort"
        app: sdm-relay
        - 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 to sdmrelay.mycompany.com
  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 node is running. Your node appears in the list of running services.

    kubectl get services
    NAME                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)           AGE
    kubernetes          ClusterIP       <none>        443/TCP           21h
    sdm-relay-service   NodePort   <none>        30001:30001/TCP   21h
  5. Log in to the Admin UI. Go to Network > Gateways or Network > Relays. The node you created appears online with a heartbeat. Click Details to view additional information.

    Kubernetes Gateway Status in Admin UI
    Kubernetes Gateway Status in Admin UI

Create a Node 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:

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 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 token you generated. Parameters are the same for gateways and relays, with a few noted exceptions.

.global.gateway.enabledOptionalfalseDefault value is used for relay deployments; set to true for gateways and to enable incoming traffic when using a gateway token
.global.gateway.service.typeRequiredNodePortDetermines the kind of service to run for the gateway, for example NodePort or Loadbalancer
.global.gateway.service.portRequired30001Indicates the port the service listens on; if using NodePort, can be different than the port set in the Admin UI
.global.gateway.service.nodePortOptional30001Matches the port value in the Admin UI when the service is set to NodePort
.global.gateway.service.loadBalancerIPOptionalNoneAssigns the IP address of an existing load balancer when the service is set to LoadBalancer
.global.secret.tokenRequiredNoneIncludes the Base64-encoded value of the relay or gateway token generated in the Admin UI
.global.deployment.repositoryRequiredpublic.ecr.aws/strongdm/relayIdentifies the location to pull the image for the gateway or relay; this can be any repository or a local image (for example, sdm-custom-image:latest)
.global.deployment.tagRequiredlatestAssigns tags for the image used for the gateway or relay
.global.deployment.imagePullPolicyRequiredAlwaysShows the policy for pulling a new image from the repo
.global.extraEnvironmentVarsOptionalNoneInjects extra environment variables in the format key:value if populated
.configmap.SDM_ORCHESTRATOR_PROBESOptional9090Shows port for a liveliness probe of the gateway or relay
.configmap.SDM_DOCKERIZEDOptionaltrueSends logs automatically to STDOUT when set to true, overriding settings in the Admin UI
.configmap.SDM_RELAY_LOG_FORMATOptionaljsonDetermines format for logs when stored locally
.configmap.SDM_RELAY_LOG_STORAGEOptionalstdoutDetermines where StrongDM activities are stored
.configmap.SDM_RELAY_LOG_ENCRYPTIONOptionalplaintextChanges the encryption of logs
  1. 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
    TEST SUITE: None
    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
  2. 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      <none>       443/TCP          38h
    service/sdm-gateway-070722-svc                            NodePort   <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
  3. Log in to the Admin UI. Go to Network > Gateways or Network > Relays. The node you created appears online with a heartbeat. Click Details to view additional information.

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>