Kubernetes Nodes

Last modified on September 17, 2024

Overview

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.

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 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 Networking > 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 Networking > 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
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: public.ecr.aws/strongdm/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

  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   10.96.0.1       <none>        443/TCP           21h
sdm-relay-service   NodePort    10.104.132.14   <none>        30001:30001/TCP   21h

  5. Log in to the Admin UI. Go to Networking > Gateways or Networking > Relays. The node you created appears online with a heartbeat. Click Details to view additional information.

    Gateway List in Admin UI
    Gateway List 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:

  • 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.
  • Have either a StrongDM gateway/relay token or else an admin token with the relay:create permission, which will be used to generate the gateway/relay token.

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.

ParameterRequiredDefaultDescription
.configmap.SDM_DOCKERIZEDOptionaltrueSends logs automatically to STDOUT when set to true, overriding settings in the Admin UI
configmap.SDM_GATEWAY_BIND_ADDR_PORTOptionalplaintextAddress where the gateway will bind, if a gateway token is to be generated
configmap.SDM_GATEWAY_LISTEN_ADDR_PORTRequiredplaintextAddress where the gateway will listen, if a gateway token is to be generated; only required if a gateway token will be generated
.configmap.SDM_ORCHESTRATOR_PROBESOptional9090Shows port for a liveliness probe of the gateway or relay
.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
configmap.SDM_RELAY_MAINTENANCE_WINDOWOptionalplaintextMaintenance window to use if a new relay token is being generated; set as semicolon-separated cron schedules, the first group being the hard-cutoff group (for example, '* 7 * * 0,6;* * * * *')
configmap.SDM_RELAY_NAMEOptionalplaintextName to use if a new relay token is being generated; must not match any existing token name; omit to use automatically generated name
configmap.SDM_RELAY_TAGSOptionalplaintextTags to use if a new relay token is being generated (for example, 'key=value,...')
.global.deployment.imagePullPolicyRequiredAlwaysShows the policy for pulling a new image from the repo
.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.extraEnvironmentVarsOptionalNoneInjects extra environment variables in the format key:value if populated
.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.loadBalancerIPOptionalNoneAssigns the IP address of an existing load balancer when the service is set to LoadBalancer
.global.gateway.service.nodePortOptional30001Matches the port value in the Admin UI when the service is set to NodePort
.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.typeRequiredNodePortDetermines the kind of service to run for the gateway (for example NodePort or Loadbalancer)
.global.secret.adminTokenOptionalNoneBase64-encoded value of the an admin token with the relay:create permission; used to generate a new relay or gateway token when there is not one already set
.global.secret.tokenRequiredNoneIncludes the Base64-encoded value of the relay or gateway token generated in the Admin UI; can be omitted if adminToken is provided

  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
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

  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   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

  3. Log in to the Admin UI. Go to Networking > Gateways or Networking > 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>