Install a Remote Network Agent in Your Cluster
Before you begin
You are familiar with what a a Remote Network Agent is and its core features.
Remote Network Agent installation methods
By default, you install a Remote Network Agent (RNA) with full access to your cluster. At a minimum, the RNA needs permissions to create, edit, and delete all kind
objects that you plan to deploy with CD-as-a-Service, in all namespaces you plan to deploy to. The RNA also requires network access to any monitoring solutions or webhook APIs that you plan to forward through it.
You can install the Remote Network Agent (RNA) in your Kubernetes cluster using one of the following:
- UI wizard
- Use a UI wizard to generate an install script that includes Client Credentials
- Install using default configuration
- Not recommended for production environments
- CLI
- Install using default configuration
- Not recommended for production environments
- kubectl
- Install using default configuration
- Not recommended for production environments
- Helm
- Install using default or advanced configuration
- Recommended for production environments
Important
If you are coming to this guide from the UI Install a Remote Network Agent screen because you want to manually install the RNA, follow the Helm instructions. Use the cluster name you created to identify your RNA. Copy the Client ID and Client Secret from the UI.
Do not close the pop-up window in the UI until you have completed RNA installation. The credentials in the pop-up window are deleted if you close the window before the RNA has connected.
Before you begin
- You have a role that allows you to create Client Credentials and connect a Remote Network Agent.
- You have access to your own Kubernetes cluster.
Generate install script using a UI wizard
You do not need to create Client Credentials for these options. The UI does that for you.
Option 1
- In the CD-as-a-Service Console, navigate to the Welcome to Continuous Deployment-as-a-Service Configuration page.
- Click Connect your Kubernetes Cluster.
- In the Select Installation Method window, select either Connect Cluster Using Helm or Connect Cluster Using Kubectl.
- In the Identify Your Cluster window, enter an agent identifier for your Remote Network Agent (RNA) in the Cluster Name field. You install this RNA in the cluster where you want to deploy your app, so create a meaningful identifier.
- Click Continue.
- Copy the script from the Connect New Remote Network Agent window and run it locally.
Option 2
- In the CD-as-a-Service Console, navigate to the Configuration page.
- Access the Networking > Agents screen.
- Click Add an Agent.
- In the Name New Remote Network Agent window, enter a name for your Remote Network Agent (RNA) in Agent Identifier. You install this RNA in the cluster where you want to deploy your app, so create a meaningful name.
- Choose I want to use my own cluster. in the Choose Cluster Type window.
- Copy the script in the Install a Remote Network Agent window and run it locally using kubectl.
Install manually using the CLI
You do not need to create Client Credentials for this option. The CLI does that for you.
-
Install the CLI if you haven’t already.
-
Log in using the CLI.
armory login
-
Make sure you are connected to your cluster.
-
Install the RNA in your cluster.
armory agent create
You choose your cluster and provide an agent identifier (cluster name) for the RNA during the installation process.
-
-
Log in using the CLI.
armory login
-
Install the RNA in your cluster.
armory agent create
You choose your cluster and provide an agent identifier (cluster name) for the RNA during the installation process.
Install manually using kubectl
Before you begin
You have Client Credentials with Remote Network Agent permissions.
Show me how
- Access the CD-as-a-Service Console.
- Go to the Configuration tab.
- If you have more than one tenant, make sure you select the desired tenant in the User context menu.
- In the left navigation menu, select Access Management > Client Credentials.
- In the upper right corner, select New Credential.
- Create a credential for your RNA. Use a descriptive name for the credential that matches what it is being used for. For example, name the credentials the same as the account name you assigned the target deployment cluster if creating a credential for an Remote Network Agent (RNA).
- Select an RBAC role from the Select Roles list. You must assign an RBAC role in order for the credential to access CD-as-a-Service.
- If the credential for is a Remote Network Agent, select Remote Network Agent.
- If you plan to use the credential to deploy from a GitHub Action or similar tool, select Deployments Full Access.
- Note the values for both Client ID and Client Secret. You need these values when configuring the RNA or any other service that you want to grant access to. Make sure to store the secret somewhere safe. You are not shown the value again.
Steps
You need Client Credentials (Client Secret and Client ID) so your RNA can communicate with CD-as-a-Service.
-
If you have access to multiple clusters, make sure you are connected to the cluster where you want to deploy the RNA. See the
kubectl
context reference for instructions. -
Install the RNA.
Replace
<client-secret>
and<client-id>
with your Client Credentials.kubectl create ns armory-rna; kubectl --namespace armory-rna create secret generic rna-client-credentials \ --type=string \ --from-literal=client-secret="<client-secret>" \ --from-literal=client-id="<client-id>"; kubectl apply -f "https://api.cloud.armory.io/kubernetes/agent/manifest?agentIdentifier=sample-cluster&namespace=armory-rna"
Install manually using Helm
Before you begin
You have Client Credentials with Remote Network Agent permissions.
Show me how
- Access the CD-as-a-Service Console.
- Go to the Configuration tab.
- If you have more than one tenant, make sure you select the desired tenant in the User context menu.
- In the left navigation menu, select Access Management > Client Credentials.
- In the upper right corner, select New Credential.
- Create a credential for your RNA. Use a descriptive name for the credential that matches what it is being used for. For example, name the credentials the same as the account name you assigned the target deployment cluster if creating a credential for an Remote Network Agent (RNA).
- Select an RBAC role from the Select Roles list. You must assign an RBAC role in order for the credential to access CD-as-a-Service.
- If the credential for is a Remote Network Agent, select Remote Network Agent.
- If you plan to use the credential to deploy from a GitHub Action or similar tool, select Deployments Full Access.
- Note the values for both Client ID and Client Secret. You need these values when configuring the RNA or any other service that you want to grant access to. Make sure to store the secret somewhere safe. You are not shown the value again.
Steps
Installation requires Helm v3+.
For advanced use cases such as restricting permissions, proxy configurations, custom annotations, labels, or environment variables, download and modify the values.yaml
for the RNA or override existing values on the command line using --set
. For information about using a values file
, see the Helm Values Files guide and the Customizing the Chart Before Installing section of the Using Helm guide.
-
Set your
kubectl
context to connect to the cluster where you want to deploy the RNA:kubectl config use-context <NAME>
-
Create the namespace for the RNA:
kubectl create ns armory-rna
-
Create secrets from your Client ID and Client Secret:
kubectl --namespace armory-rna create secret generic rna-client-credentials --type=string --from-literal=client-secret=<your-client-secret> --from-literal=client-id=<your-client-id>
The examples use Kubernetes secrets to encrypt the value. You supply the encrypted values in the Helm command to install the RNA.
-
You can install the RNA with default permissions and values or you can customize using a
values.yaml
file.For most scenarios, you install one RNA per cluster. Use the
agentIdentifier
parameter to give each RNA a unique name. When you deploy your app, you specify which RNA to use, so Armory recommends creating a meaningful name that identifies the cluster.Default values
The encrypted values for
clientId
andclientSecret
reference the Kubernetes secrets you generated in an earlier step.helm upgrade --install armory-rna armory/remote-network-agent \ --set agentIdentifier=<rna-name> \ --set 'clientId=encrypted:k8s!n:rna-client-credentials!k:client-id' \ --set 'clientSecret=encrypted:k8s!n:rna-client-credentials!k:client-secret' \ --namespace armory-rna
Customized values
You can specify the path to your customized values file using
-f <your-path>values.yaml
or you can override values using the command line--set <key:value>
. Refer to the Customizing the Chart Before Installing section in the Helm docs. -
You can go to the Agents page in the CD-as-a-Service Console to verify that your RNA has been installed and is communicating with CD-as-a-Service. If you do not see the RNA, check your cluster logs to see if the RNA is running.
What’s next
View your connected Remote Network Agents to see data such as the last time CD-as-a-Service detected a heartbeat.
Feedback
Was this page helpful?
Thank you for letting us know!
Sorry to hear that. Please tell us how we can improve.
Last modified July 20, 2023: (37290cf)