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.

  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.

  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.

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

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

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.

ParameterRequiredDefaultDescription
.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.repositoryRequiredquay.io/sdmrepo/relayIdentifies 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.tagRequiredlatestAssigns tags for the image used for the StrongDM 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
    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 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>