Install a Remote Network Agent in Production Using Helm
Production installation
Armory recommends and supports installing the Remote Network Agent using the armory/remote-network-agent
Helm chart. Using a values
file, you can configure advanced options such as:
- Secrets management outside of Kubernetes (AWS Secrets Manager, AWS S3, Vault, Kubernetes Injector)
- Agent proxy settings
- Pod labels
- Pod annotations
- Pod environment variables
- Pod resource requests and limits
- Pod DNS settings
- Pod Node selection
- Pod affinity
- Pod tolerations
- Log configuration
- Disable Kubernetes cluster mode
- Metrics
Before you begin
You have installed Helm v3+.
You configure advanced options in a
values
file, so you should be familiar with using that file to customize a chart. For more information, see the Helm docs:You have created a namespace for your RNA:
kubectl create ns armory-rna
. Since you pass the namespace to thehelm
command, you can use a different namespace. This guide assumes you have created anarmory-rna
namespace.
Installation using Helm consists of the following steps:
Configure your installation in the
values.yaml
file, which you should download from the repo.
Click to view the values file
# clientId and clientSecret are your CD-as-a-Service Client Credentials, which must have the `Remote Network Agent` scope.
# Go to https://console.cloud.armory.io/configuration/credentials to create credentials or add the scope.
#
# You can configure the clientId and clientSecret using a Kubernetes secret or an Armory Continuous Deployment Secrets token.
#
# EX: using Kubernetes secrets
# Save your Client Credentials as a Kubernetes secret
# kubectl -ns armory-rna create secret generic rna-client-credentials --type=string --from-literal=client-secret=xxx-yyy-ooo --from-literal=client-id=zzz-ooo-qqq
# Set the clientSecret value as:
# clientSecret: encrypted:k8s!n:rna-client-credentials!k:client-secret
#
# EX: using AWS Secrets Manager
# ex: clientSecret: encrypted:secrets-manager!r:us-west-2!s:some-aws-sm-secret-name!k:client-secret
# See:
# - https://docs.armory.io/continuous-deployment/armory-admin/secrets/
# - https://docs.armory.io/continuous-deployment/armory-admin/secrets/secrets-kubernetes/ (ignore the note saying it only works with Operator; it has been back ported to RNA)
# - https://docs.armory.io/continuous-deployment/armory-admin/secrets/secrets-vault/
# - https://docs.armory.io/continuous-deployment/armory-admin/secrets/secrets-aws-sm/
# - https://docs.armory.io/continuous-deployment/armory-admin/secrets/secrets-gcs/
# - https://docs.armory.io/continuous-deployment/armory-admin/secrets/secrets-s3/
#
# If you have a process for injecting secrets as env vars, such as a vault injector sidecar, you can set the clientSecret to an env var here.
# ex: clientSecret: '{{ env.MY_CLIENT_SECRET }}'
# ex: https://www.vaultproject.io/docs/platform/k8s/injector
#
# Do NOT use the plain text value of clientSecret in the values file or as an arg to the Helm chart!
clientId:
clientSecret:
#############################################################################
#
# All settings below this line are optional
#
#############################################################################
# Defaults to the name used when creating the Client Credentials for this RNA.
# This is that name that your CD-as-a-Service deployment references to deploy to the cluster that the RNA is running in.
agentIdentifier:
replicaCount: 2
image:
repository: armory/remote-network-agent
pullPolicy: IfNotPresent
# Overrides the image tag whose default is the chart appVersion.
tag: ""
# imagePullSecrets:
# - name: regcred
imagePullSecrets: []
# Proxy settings if the RNA needs to go through a proxy to connect the Agent Hub
# See the comments below or the following for more technical information:
# - https://github.com/grpc/grpc-go/blob/master/Documentation/proxy.md
# - https://pkg.go.dev/golang.org/x/net/http/httpproxy#FromEnvironment
proxy:
enabled: false
# Either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.
# An error is returned if the value is a different form.
url: https://proxy.internal.example.com:443
# nonProxyHosts specifies a string that contains comma-separated values specifying hosts that should be excluded from proxying.
#
# Each value is represented by an IP address prefix (1.2.3.4), an IP address prefix in CIDR notation (1.2.3.4/8),
# a domain name, or a special DNS label (*).
#
# An IP address prefix and domain name can also include a literal port number (1.2.3.4:80).
# A domain name matches that name and all subdomains. A domain name with a leading "." matches subdomains only.
# For example "foo.com" matches "foo.com" and "bar.foo.com"; ".y.com" matches "x.y.com" but not "y.com".
# A single asterisk (*) indicates that no proxying should be done.
# A best effort is made to parse the string and errors are ignored.
nonProxyHosts:
# When Kubernetes cluster account mode is enabled, installation creates a ServiceAccount, ClusterRole, and ClusterRoleBinding.
# The created ServiceAccount with ClusterRoleBinding is applied to the RNA.
# The RNA then registers itself as a deployable Kubernetes target from within CD-as-a-Service.
#
# When Kubernetes cluster account mode is disabled, the RNA only allows you to make network calls to networked resources.
kubernetes:
enableClusterAccountMode: true
# RBAC permissions granted to the ServiceAccount for the RNA
clusterRoleRules:
- apiGroups: [ "*" ]
resources: [ "*" ]
verbs: [ "*" ]
serviceAccount:
# Annotations to add to the ServiceAccount
annotations: {}
# Additional environment variables to add to the Pods
# podEnvironmentVariables:
# - name: FOO
# value: bar
podEnvironmentVariables: []
# Additional labels to add to the Pods:
# podLabels:
# key: value
podLabels: {}
log:
# Can be set to console, console-wide (all the same metadata that gets added to json output) or json
type: console
# Disable color output
disableColor: false
# debug,info,warn,error
level: info
# Additional annotations for Pods
# podAnnotations:
# prometheus.io/scrape: "true"
# prometheus.io/path: "/metrics"
# prometheus.io/port: "8080"
# prometheus.io/scheme: "http"
# key: value
podAnnotations: {}
# Configure Pod resource requests and limits
# https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits
resources: {}
# limits:
# cpu: 200m
# memory: 512Mi
# requests:
# cpu: 100m
# memory: 256Mi
# Sets Pod's priorityClassName.
priorityClassName: ""
# Sets the RNA's Pod DNS policy
# https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy
dnsPolicy:
# Sets Pod's dnsConfig.
# https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config
dnsConfig: {}
# Sets Pod/Node affinities.
# https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
affinity: {}
# Sets Pod's node selector.
# https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
nodeSelector: {}
# Sets Pod's tolerations to node taints.
# https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
tolerations: []
Configure required settings
If you don’t configure these in the file, you must pass them on the command line using
--set <key>:<value>
.
clientId
andclientSecret
: the Client ID and Client Secret from your Client Credentials; you should encrypt the Client ID and Client Secret as a secret in a supported secrets manager such as Kubernetes or AWS Secrets Manager.For example, to create a Kubernetes secret, execute the following:
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>
Then you would configure
clientId
andclientSecret
like this:clientId: encrypted:k8s!n:rna-client-credentials!k:client-id clientSecret: encrypted:k8s!n:rna-client-credentials!k:client-secret
See the comments in the
values.yaml
file for examples using other secrets managers.agentIdentifier
: the name of your Remote Network Agent; you use this name in your deployment config file to identify your deployment target cluster; for example, if youragentIdentifer
isprod-eu
, yourtargets.<targetname>.account
isprod-eu
.
Configure optional settings
Replica count
replicaCount: <int>
Default: 2
replicas. Change this value to increase the number of replicas.
Image
The armory/remote-network-agent
image is in a public registry. If you plan to host the image in a private registry, you should know how to pull an image from a private registry.
image:
repository: armory/remote-network-agent
pullPolicy: IfNotPresent
tag: ""
# imagePullSecrets:
# - name: regcred
imagePullSecrets: []
image
repository
: The default isarmory/remote-network-agent
, which is public.pullPolicy
: Image pull policy; one ofIfNotPresent
,Always
, orNever
.tag
: Specify a tag only if you want to override the default image tag, which is the chartappVersion
.
imagePullSecrets
: The secret for pulling an image from a private registry. This field is required only if you are hosting the RNA image in your own private registry.
Proxy
Configure your proxy in the proxy
block. The values.yaml
file contains detailed comments on allowable values for these fields.
proxy:
enabled: false
url: <proxy-url>
nonProxyHosts:
Kubernetes permissions
kubernetes:
enableClusterAccountMode: true
# RBAC permissions granted to the ServiceAccount for the RNA
clusterRoleRules:
- apiGroups: [ "*" ]
resources: [ "*" ]
verbs: [ "*" ]
serviceAccount:
# Annotations to add to the ServiceAccount
annotations: {}
enableClusterAccountMode
enableClusterAccountMode: true
: Installation creates a ServiceAccount, ClusterRole, and ClusterRoleBinding. Then installation applies the ServiceAccount with ClusterRoleBinding to the RNA. Lastly, the RNA registers itself as a deployment target within CD-as-a-Service.enableClusterAccountMode: false
: The RNA only allows you to make network calls to networked resources. You have to configure Kubernetes accounts in the CD-as-a-Service Console to have Kubernetes deployment targets.
clusterRoleRules
andserviceAccount
Configure ClusterRole and ServiceAccount in the
kubernetes.clusterRoleRules
andkubernetes.serviceAccount
blocks. At a minimum, the RNA needs permissions to create, edit, and delete allkind
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.See the Kubernetes Documentation’s Using RBAC Authorization guide for detailed info on configuring permissions.
Pods
podEnvironmentVariables: []
# - name: FOO
# value: bar
podLabels: {}
# key: value
resources: {}
# limits:
# cpu: 200m
# memory: 512Mi
# requests:
# cpu: 100m
# memory: 256Mi
priorityClassName: ""
dnsPolicy:
dnsConfig: {}
affinity: {}
nodeSelector: {}
tolerations: []
podEnvironmentVariables
: Environment variables to add to the Pods. See Define Environment Variables for a Container.podLabels
: Labels to add to the Pods. See Labels and Selectors.resources
: Configure Pod requests and limits. See Resource Management for Pods and Containers.priorityClassName
: PriorityClass name. See Pod Priority and Preemption.dnsPolicy
: Set the Pod’s DNS policy. See Pod’s DNS Policy.dnsConfig
: Set the Pod’s DNS config. See Pod’s DNS Config.affinity
: Set the Pod’s affinities. See Affinity and anti-affinity.nodeSelector
: Set the Pod’snodeSelector
. See Assigning Pods to Nodes.tolerations
: Set the Pod’s tolerations to node taints. See Taints and Tolerations.
Metrics
The RNA exposes an endpoint on :8080/metrics
that can serve Prometheus or OpenMetrics format.
If you have a Prometheus or OpenMetrics scraper installed in your cluster, you can enable the following annotations:
podAnnotations:
prometheus.io/scrape: "true"
prometheus.io/path: "/metrics"
prometheus.io/port: "8080"
prometheus.io/scheme: "http"
Logging
By default, the RNA logs in human-readable text. However, you can enable structured JSON logging, which is often more appropriate for log aggregation by tools like Splunk and New Relic.
log:
type: json
disableColor: false
level: info
type
: log output type; specify one of the following:console
console-wide
: all the same metadata that gets added to JSON outputjson
disableColor
:true|false
; turn off color outputlevel
: specify one ofdebug
,info
,warn
, orerror
Generate and preview the manifests
After you have completed your advanced configuration in the values.yaml
file, you can use the helm template
command to render the Kubernetes manifests.
helm template armory-rna armory/remote-network-agent --values values.yaml --namespace armory-rna
Install the RNA
helm upgrade --install armory-rna armory/remote-network-agent -f <path-to-values.yaml> \
--namespace <namespace>
Replace <namespace>
with the namespace you created for the RNA.
You can manage the RNA with Terraform with your Infrastructure as Code (IaC)
resource "helm_release" "armory-rna" {
name = "armory-rna"
chart = "remote-network-agent"
repository = "https://armory.jfrog.io/artifactory/charts"
namespace = "<namespace>"
cleanup_on_fail = true
values = [file("<path-to-values.yaml>")]
}
- Replace
<namespace>
with the namespace you created for the RNA. - Replace
<path-to-values.yaml>
with the path to yourvalues.yaml
file.
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.
Feedback
Was this page helpful?
Thank you for letting us know!
Sorry to hear that. Please tell us how we can improve.
Last modified October 26, 2023: (8182348)