Merge pull request #101 from nrwl/steve/chore/agents-chart-docs

chore(charts): get ready for 1.0.0 release

charts/nx-agents/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 name: nx-agents
 description: Nx Cloud Agents Helm Chart
 type: application
-version: 1.0.0-rc.7
+version: 1.0.0
 maintainers:
   - name: nx
     url: "https://nx.app/"

charts/nx-agents/ci/basic-moreenv.yaml

@@ -1,7 +1,4 @@
 global:
-  imageRegistry: 'us-east1-docker.pkg.dev/nxcloudoperations'
-  imageTag: ''
-  imageRepository: 'nx-cloud-enterprise-public'
   namespace: 'nx-cloud-workflows'
 
 naming:
@@ -35,9 +32,9 @@ controller:
     loadBalancerSourceRanges: []
     annotations: {}
   image:
-    registry: ''
+    registry: 'us-east1-docker.pkg.dev/nxcloudoperations'
     imageName: nx-cloud-workflow-controller
-    repository: ''
+    repository: 'nx-cloud-enterprise-public'
     tag: test.0219162846
     pullPolicy: Always
   resources:

charts/nx-agents/ci/basic-values.yaml

@@ -1,7 +1,4 @@
 global:
-  imageRegistry: 'us-east1-docker.pkg.dev/nxcloudoperations'
-  imageTag: ''
-  imageRepository: 'nx-cloud-enterprise-public'
   namespace: 'nx-cloud-workflows'
 
 naming:
@@ -26,9 +23,9 @@ controller:
     loadBalancerSourceRanges: []
     annotations: {}
   image:
-    registry: ''
+    registry: 'us-east1-docker.pkg.dev/nxcloudoperations'
     imageName: nx-cloud-workflow-controller
-    repository: ''
+    repository: 'nx-cloud-enterprise-public'
     tag: test.0219162846
     pullPolicy: Always
   resources:

charts/nx-agents/templates/_images.yml

@@ -1,20 +1,14 @@
 {{/*
 Return the proper image name
 Helper copied from bitnami/common: https://github.com/bitnami/charts/blob/main/bitnami/common/templates/_images.tpl
-and modified to support global imageTag
-{{ include "common.images.image" ( dict "imageRoot" .Values.path.to.the.image "global" .Values.global "image" .Values.image ) }}
+with the entire global option removed
 */}}
 {{- define "nxCloud.images.common" }}
 {{- $registryName := .imageRoot.registry }}
-{{- $repositoryName := .imageRoot.repository | default .global.imageRepository }}
+{{- $repositoryName := .imageRoot.repository  }}
 {{- $imageName := .imageRoot.imageName }}
 {{- $separator := ":" }}
-{{- $termination := .global.imageTag | default .imageRoot.tag | toString }}
-{{- if .global }}
-    {{- if .global.imageRegistry }}
-     {{- $registryName = .global.imageRegistry }}
-    {{- end }}
-{{- end }}
+{{- $termination := .imageRoot.tag | toString }}
 {{- if .imageRoot.digest }}
     {{- $separator = "@" }}
     {{- $termination = .imageRoot.digest | toString }}
@@ -31,5 +25,5 @@ and modified to support global imageTag
 Return proper nx-cloud-workflow-controller image name
 */}}
 {{- define "nxCloud.images.workflowController.image" }}
-{{- include "nxCloud.images.common" (dict "imageRoot" .Values.controller.image "global" .Values.global) }}
+{{- include "nxCloud.images.common" (dict "imageRoot" .Values.controller.image) }}
 {{- end }}

charts/nx-agents/values.yaml

@@ -1,13 +1,19 @@
 global:
-  imageRegistry: ''
-  imageTag: ''
-  imageRepository: 'nxprivatecloud'
+  # This is the namespace for all workflow resources, it will be where all items from this chart are
+  # created as well as where your agents run.
   namespace: 'nx-cloud-workflows'
 
 naming:
+  # Overrides the app name (defined in _helpers.tpl) used when installing the chart
   nameOverride: ''
-  fullNameOverride: ''
 
+# Our workflow agents use 2 service accounts: 1 for the controller itself that has more permissions and 1 for the runner
+# which is more constrained
+# Each Service Account definition allows you to attach additional annotations that can be applied to the controller service
+# account. For instance, if you use workload identity on a platform such as GCP, you can add the annotation to the service
+# account here as we do internally (please see your provider's documentation for more information on workload
+# identity and how to use it):
+# `iam.gke.io/gcp-service-account: <SA_ID>@<PROJECT>.iam.gserviceaccount.com`
 serviceAccounts:
   controller:
     name: nx-cloud-workflow-controller
@@ -16,33 +22,63 @@ serviceAccounts:
     name: nx-cloud-workflow-runner
     annotations: {}
 
+# The controller is the main component of the workflow system. It is responsible for managing the state of workflows, starting
+# new runs in your cluster, and managing the agents that run your workflows. It should be internally accessible from both
+# your nx-api and frontend deployments in your application cluster. Within Nx, we accomplish this with a service of type
+# LoadBalancer using a reserved internal IP address.
 controller:
+  # Options specifically for the controller deployment object
   deployment:
     port: 9000
     annotations: {}
+
+    # If you wish to steer placement of the controller pod(s) these will be applied to the pod spec. Currently, we recommend
+    # using taints and tolerations at this time to isolate your controller from the runner pods.
     affinity: {}
+
+    # While we will be expanding future support for node affinity, the most reliable way to keep your controller pods and
+    # agent pods separate is to use taints and tolerations.
     tolerations: {}
     nodeSelector: {}
+
+    # These are additional args that will be passed to the controller binary when it starts. This is useful for passing
+    # certain configuration options to the controller. Available options are documented in the controller's help output.
+    # e.g. `docker run --rm -it <PATH_TO_CONTROLLER_IMAGE> /nx-cloud-workflow-controller --help`
     args: {}
     strategy:
       rollingUpdate:
         maxSurge: 25%
         maxUnavailable: 25%
       type: RollingUpdate
     envFrom: []
-    env: {}
+    # Specific ENV vars that will be passed to the controller binary when it starts. This is useful for passing certain
+    # configuration options to the controller. For instance, when using GCS object storage, you can set
+    # NX_CLOUD_GCS_BUCKET and NX_CLOUD_GCS_PROJECT_ID to the appropriate values which will trigger the controller to
+    # target gcs. Please note, in this case the executor will also need to be configured to use GCS which can be done
+    # via the executor.env field.
+    env: []
   service:
     port: 9000
+    # We support ClusterIP and LoadBalancer service types.
     type: ClusterIP
+    # If using LoadBalancer, you can specify a reserved internal IP address.
     loadBalancerIP: ''
+    # If using LoadBalancer, you can specify a list of CIDRs that are allowed to access the LoadBalancer internally
     loadBalancerSourceRanges: []
+    # Additional annotations to pass to the service. For instance, in our GKE setups we use things like
+    # `networking.gke.io/load-balancer-type: Internal` to ensure the load balancer is internal and
+    # `networking.gke.io/internal-load-balancer-allow-global-access: "true"` to allow access from subnets in other regions
     annotations: {}
+  # If you are using internal images for your controller instead of our publicly available ones, feel free to set
+  # the values here.
   image:
     registry: ''
     imageName: nx-cloud-workflow-controller
     repository: ''
     tag: latest
     pullPolicy: Always
+  # These are our recommended resources for the controller. However we have noted that a request as low as 0.2 CPU and 0.5Gi
+  # memory can work for many cases
   resources:
     limits:
       memory: '1Gi'
@@ -51,9 +87,19 @@ controller:
       memory: '0.5Gi'
       cpu: '0.5'
 
+# These values will be passed as `--executor-env` flags to the controller. This is useful for passing certain configuration options
+# to each agent pod. For instance, when using GCS object storage above, you can set NX_CLOUD_GCS_BUCKET and NX_CLOUD_GCS_PROJECT_ID
+# here to ensure each executor can upload to the correct bucket. These values are interpreted AFTER the controller.deployment.env values meaning
+# you can refer to the ENV you set above (e.g. `NX_CLOUD_GCS_BUCKET: "$(NX_CLOUD_GCS_BUCKET)"`). Unlike controller.deployment.env, these values
+# should be set as a set of key-value pairs and not the literal name/value setting you would use in controller.deployment.env.
 executor:
   env: {}
 
+# The daemonset is used to ensure file watch limits are set correctly on each node in the cluster. This can ensure that your
+# agents will not fail due to shared resources being exhausted. This is especially important if you are running many agents.
+# However if you have the ability to set these values on the actual nodes in your cluster, you can disable this feature.
+# Additionally this feature can be retained, and you can update the provided script to run other things you would like on
+# each node in your cluster.
 daemonset:
   enabled: true
   script: |
@@ -68,6 +114,9 @@ daemonset:
     # check that the new value was applied
     cat /proc/sys/fs/inotify/max_user_watches
 
+# Currently, we support AWS S3 (in addition to GCS) as a storage backend for your workflow artifacts if the key and secret are provided.
+# If set, ensure to provide the proper ENV mappings that aws client libararies expect such as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
+# for both the controller and executor. Additionally point the controller to the correct bucket and region with the NX_CLOUD_AWS_BUCKET variable
 secret:
   name: ''
   awsS3AccessKeyId: ''