# Kubernetes Nodes ### Overview This guide describes how to create a node (gateway or relay) in your Kubernetes cluster. You can follow the [manual approach](#create-a-node-manually) or optionally use the [Helm chart method](#create-a-node-with-helm) to install your node. If you're interested in using a proxy cluster rather than a gateway or relay, see the [Proxy Clusters in Kubernetes](/admin/networking/proxy-clusters/kubernetes-proxy-clusters.md) guide. ### Prerequisites To be successful when using this guide, you must meet the following general requirements: * Ensure that you are an Administrator in StrongDM. * Be sure that your Kubernetes cluster(s) is at version 1.16 or later and has publicly accessible nodes and stable IPs. * Install the [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool locally to interact with your Kubernetes clusters. * If you are using [Nginx Ingress Controller](https://kubernetes.github.io/ingress-nginx/), manually patch your services to [allow TCP and UDP traffic](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/). * If you are using Helm to manage your node, install Helm 3.0 or later locally. ### Manage Kubernetes Nodes With Helm StrongDM has a Helm chart that can be used to create a node within your cluster, register it with your StrongDM organization, and then register the cluster itself as a resource in your StrongDM organization as well. All you need to do this is to have an [admin token](/admin/principals/admin-tokens.md) that gives you permission to create nodes and cluster resources. 1. Create a `values.yaml` file for use with the Helm chart. You can see a reference schema of the available options in the `sdm-relay` GitHub repository [values.yaml](https://github.com/strongdm/charts/blob/main/deployments/sdm-relay/values.yaml) file or on [ArtifactHub](https://artifacthub.io/packages/helm/strongdm/sdm-proxy) for further customization. The minimum values that must be specified in order to create the node, register it with your organization, and register the cluster as a resource are shown in the following example. ```yaml strongdm: auth: # StrongDM authentication sources adminToken: "" # Specify an admin token to allow the chart to create and register your node autoCreateNode: # create/register the node in StrongDM, using the SDM_ADMIN_TOKEN enabled: true autoRegisterCluster: # register this cluster as a resource in StrongDM enabled: true ``` 2. Install the Helm chart. Replace `` with a unique and meaningful name. ```shell helm repo add strongdm https://helm.strongdm.com/stable/ helm install strongdm/sdm-relay -f values.yaml helm status ``` 3. If you wish, you can verify that the chart created the node, and that the node and resource were added to your StrongDM organization with the following methods: 1. You can check that the node is running in your cluster with `kubectl get services`, which should output something similar to the following, with an `sdm-relay-service` running: ```shell NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE kubernetes ClusterIP 10.96.0.1 443/TCP 21h sdm-relay-service NodePort 10.104.132.14 30001:30001/TCP 21h ``` 2. You can check that the node is added to StrongDM by looking in the Admin UI under **Networking** > **Gateways** or **Networking** > **Relays**, or by using the CLI (`sdm admin nodes list`). If you did not specify any settings for your node, it will be named something random, but the IP will match your cluster. 3. You can check that the cluster is added to StrongDM as a resource by looking in the Admin UI under **Resources** > **Managed Resources**, or by using the CLI (`sdm admin clusters list`). If you did not specify any settings for your cluster resource, it will be named something based on your chosen ``. {% hint style="info" %} Note that this example is creating a relay as the default, which assumes that your organization has one or more working gateways already, as relays are egress-only, meaning that they do not accept direct traffic from clients. You can alter this behavior by adding `gateway.enabled:true` to your chart, as shown in the GitHub repository [values.yaml](https://github.com/strongdm/charts/blob/main/deployments/sdm-relay/values.yaml) file or on [ArtifactHub](https://artifacthub.io/packages/helm/strongdm/sdm-proxy). You can also customize further in this configuration, such as naming the gateway or relay something specific or creating it with custom maintenance windows. {% endhint %} #### Upgrade the sdm-relay Helm chart To upgrade the sdm-relay Helm chart, run the following command. For more, see the [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) command documentation. ```shell helm upgrade strongdm/sdm-relay ``` {% hint style="info" %} The nodes will automatically keep themselves up to date without you needing to upgrade the Helm chart. You only need to upgrade if you want a feature that is only available in a newer version of the sdm-relay Helm chart. {% endhint %} #### 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](https://helm.sh/docs/helm/helm_uninstall/) reference documentation. ```shell helm uninstall ``` ### Create a Node Manually In some circumstances, you may wish to deploy a gateway or relay in a Kubernetes cluster without using Helm. You will need to create a gateway token or relay token in StrongDM, install your node and configure it in your cluster, and then verify that it is connected to StrongDM. #### 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. **Create a gateway token** To create a gateway token, follow these steps. 1. Log in to the Admin UI. 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 generate a gateway token via the CLI instead, see [sdm admin nodes create-gateway](/references/cli/admin/nodes/create-gateway.md). 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`. {% hint style="info" %} When using Helm to install the gateway or relay, check the [Helm chart configurations](#install-the-sdm-relay-helm-chart) for additional port information. {% endhint %} **Create a relay token** To register the node and create a relay token, follow these steps. 1. Log in to the Admin UI. 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 relay token via the CLI instead, see [sdm admin nodes create](/references/cli/admin/nodes/create.md). 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`. {% hint style="info" %} When using Helm to install the gateway or relay, check the [Helm chart configurations](#install-the-sdm-relay-helm-chart) for additional port information. {% endhint %} #### Create your node 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](#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. ```yaml 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. ```yaml 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 ``` {% hint style="info" %} 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. {% endhint %} 3. Create the deployment and activate your gateway. You may have to specify a directory for the YAML file. ```shell kubectl create -f name-of-gateway-file.yml ``` 4. Verify the node is running. Your node appears in the list of running services. ```shell kubectl get services ``` ```shell NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE kubernetes ClusterIP 10.96.0.1 443/TCP 21h sdm-relay-service NodePort 10.104.132.14 30001:30001/TCP 21h ``` {% hint style="info" %} Relay deployments are not listed under kubectl services. {% endhint %} 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. ![](/files/L3Sc7fXJXChiaxAtfwAP) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.strongdm.com/admin/networking/gateways-and-relays/kubernetes-nodes.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.