diff --git a/charts/lightrun-agents/.helmignore b/charts/lightrun-agents/.helmignore new file mode 100644 index 0000000..0e8a0eb --- /dev/null +++ b/charts/lightrun-agents/.helmignore @@ -0,0 +1,23 @@ +# Patterns to ignore when building packages. +# This supports shell glob matching, relative path matching, and +# negation (prefixed with !). Only one pattern per line. +.DS_Store +# Common VCS dirs +.git/ +.gitignore +.bzr/ +.bzrignore +.hg/ +.hgignore +.svn/ +# Common backup files +*.swp +*.bak +*.tmp +*.orig +*~ +# Various IDEs +.project +.idea/ +*.tmproj +.vscode/ diff --git a/charts/lightrun-agents/Chart.yaml b/charts/lightrun-agents/Chart.yaml new file mode 100644 index 0000000..0a6261d --- /dev/null +++ b/charts/lightrun-agents/Chart.yaml @@ -0,0 +1,18 @@ +apiVersion: v2 +name: lightrun-agents +description: A Helm chart for Kubernetes that deploy lightrun agents CRDs + +# A chart can be either an 'application' or a 'library' chart. +# +# Application charts are a collection of templates that can be packaged into versioned archives +# to be deployed. +# +# Library charts provide useful utilities or functions for the chart developer. They're included as +# a dependency of application charts to inject those utilities and functions into the rendering +# pipeline. Library charts do not define any templates and therefore cannot be deployed. +type: application + +# This is the chart version. This version number should be incremented each time you make changes +# to the chart and its templates, including the app version. +# Versions are expected to follow Semantic Versioning (https://semver.org/) +version: 0.0.1 diff --git a/charts/lightrun-agents/README.md b/charts/lightrun-agents/README.md new file mode 100644 index 0000000..ec91aec --- /dev/null +++ b/charts/lightrun-agents/README.md @@ -0,0 +1,171 @@ +# Helm Chart for Deploying Lightrun Agents +This Helm chart allows you to deploy and manage Lightrun Agents as custom resources in your Kubernetes cluster. +Currently only java based agents are supported. +The LightrunJavaAgent custom resource will be configured based on the values provided in the values.yaml file. + +## Prerequisites +- Kubernetes 1.16+ +- Helm 3.0+ +- Ability to fetch images of the init containers from [Lightrun Repository Dockerhub](https://hub.docker.com/u/lightruncom). or alternatively have them available in private registry. +## Installation +### 1 - Add the repo to your Helm repository list +```shell +helm repo add lightrun-k8s-operator https://lightrun-platform.github.io/lightrun-k8s-operator + +``` +### 2 - Prepare values.yaml +The "values.yaml" file contains the following configurable parameters for each java agent object: + +| Parameter | Description | Default | +|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| `javaAgents[].agentCliFlags` | [Command-line flags for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#additional-command-line-flags). | Optional `""` (empty string) | +| `javaAgents[].agentConfig` | [Additional configuration for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#agent-flags) | Optional `{}` (empty map) | +| `javaAgents[].agentEnvVarName` | Specifies the Java environment variable name used for adding `--agentpath` | Optional (if not provided, defaults to `"JAVA_TOOL_OPTIONS"`) | +| `javaAgents[].agentName` | Custom name to assign to the Lightrun Java Agent. | Optional (if not provided, defaults to pod name) | +| `javaAgents[].agentPoolCredentials.existingSecret` | Name of an existing Kubernetes secret containing api key and pinned cert hash for agent pool. [secret example](https://github.com/lightrun-platform/lightrun-k8s-operator/blob/main/examples/lightrunjavaagent.yaml#L64-L73) | Optional (if not provided, defaults to `name-secret`) | +| `javaAgents[].agentPoolCredentials.apiKey` | Lightrun agent API key. | Required if `existingSecret` not set | +| `javaAgents[].agentPoolCredentials.pinnedCertHash` | 64 character sha256 certificate public key hash for pinning | Required if `existingSecret` not set | +| `javaAgents[].agentTags` | [List of Lightrun Java Agent tags.](https://docs.lightrun.com/jvm/tagging/#manage-lightrun-java-agent-tags) | Optional `[]` (empty list) | +| `javaAgents[].containerSelector` | Selector for containers within the deployment to inject the Lightrun Java Agent. | Required | +| `javaAgents[].deploymentName` | Name of the Kubernetes deployment to attach the Lightrun Java Agent. | Required | +| `javaAgents[].initContainer.image` | Image for the Lightrun Java Agent init container. | Required | +| `javaAgents[].initContainer.sharedVolumeMountPath` | Mount path for the shared volume in the init container. | Optional (if not provided, defaults to `"/lightrun"`" | +| `javaAgents[].initContainer.sharedVolumeName` | Name of the shared volume for the init container. | Optional (if not provided, defaults to `"lightrun-agent-init"`" | +| `javaAgents[].name` | Name of the Lightrun Java Agent custom resource. | Required | +| `javaAgents[].namespace` | Namespace of the Lightrun Java Agent custom resource. Must be in the same namespace as the workload | Required | +| `javaAgents[].serverHostname` | Hostname of the Lightrun server to connect the agent. | Required | + +#### 2.1 - Set `initContainer.image` + +Based on your workload's OS and architecture, you should select the appropriate DockerHub repository from the following options: +- [linux amd64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-linux/general) +- [linux arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-linux-arm64/general) +- [alpine amd64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine/general) +- [alpine arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine-arm64/general) + +After determining the appropriate image, you'll need to choose a tag. The tag can either be "latest," which corresponds to the most up-to-date version, or it can be a specific Lightrun version following the convention `-init.`. Typically, the `` part is 0, but it's always good to verify on the DockerHub repository. + +For your convenience, here are some possible combinations of how the final image might look: +```text +Linux amd64 with the latest version -> lightruncom/k8s-operator-init-java-agent-linux:latest +Linux amd64 with a specific version -> lightruncom/k8s-operator-init-java-agent-linux:1.39.1-init.0 +Linux arm64 with the latest version -> lightruncom/k8s-operator-init-java-agent-linux-arm64:latest +Linux arm64 with a specific version -> lightruncom/k8s-operator-init-java-agent-linux-arm64:1.39.1-init.0 +Alpine amd64 with the latest version -> lightruncom/k8s-operator-init-java-agent-alpine:latest +Alpine amd64 with a specific version -> lightruncom/k8s-operator-init-java-agent-alpine:1.39.1-init.0 +Alpine arm64 with the latest version -> lightruncom/k8s-operator-init-java-agent-alpine-arm64:latest +Alpine arm64 with a specific version -> lightruncom/k8s-operator-init-java-agent-alpine-arm64:1.39.1-init.0 +``` +#### 2.2 Install the chart + +When installing the chart, it's important to understand that the -n flag provided in the helm install command does not determine where the actual resources will be deployed. Instead, deployment is controlled by the javaAgents[].namespace parameter for each object in the values.yaml file. + +Use the -n flag to specify a namespace, either using the same namespace where your Lightrun Kubernetes Operator is installed or creating a new namespace specifically for this purpose, such as "lightrun-agents". This namespace will be referenced if you need to uninstall the chart later. +```bash +helm install lightrun-k8s-operator/lightrun-agents -n -f values.yaml +``` + +## Examples +### Basic +- The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. + +- The `my-service-2` uses an `existingSecret` named `my-existing-secret` +```yaml +javaAgents: + - name: 'my-service-1' + namespace: 'my-namespace-1' + deploymentName: "my-deployment-1" + containerSelector: + - my-container-1 + serverHostname: 'lightrun.example.com' + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + agentPoolCredentials: + existingSecret: "" + apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + pinnedCertHash: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + agentTags: + - env-production + - service-my-server + - region-us_east_1 + - provider-aws + - name: 'my-service-2' + namespace: 'my-namespace-2' + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + deploymentName: "my-deployment-2" + containerSelector: + - my-container-2 + serverHostname: 'lightrun.example.com' + agentPoolCredentials: + existingSecret: "my-existing-secret" + apiKey: "" + pinnedCertHash: "" + agentTags: + - env-production + - service-my-other-server + - region-us_east_1 + - provider-aws +``` + +### Full +- The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. + +- The `my-service-2` uses an `existingSecret` named `my-existing-secret` +```yaml +javaAgents: + - name: 'my-service-1' + namespace: 'my-namespace-1' + deploymentName: "my-deployment-1" + containerSelector: + - my-container-1 + serverHostname: 'lightrun.example.com' + agentEnvVarName: '_JAVA_OPTIONS' + agentConfig: + max_log_cpu_cost: "2" + agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + sharedVolumeName: 'my-shared-volume' + sharedVolumeMountPath: '/mypath' + agentPoolCredentials: + existingSecret: "" + apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + pinnedCertHash: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + agentTags: + - env-production + - service-my-server + - region-us_east_1 + - provider-aws + - name: 'my-service-2' + namespace: 'my-namespace-2' + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + sharedVolumeName: 'my-shared-volume' + sharedVolumeMountPath: '/mypath' + deploymentName: "my-deployment-2" + containerSelector: + - my-container-2 + serverHostname: 'lightrun.example.com' + agentEnvVarName: 'JAVA_OPTS' + agentConfig: + max_log_cpu_cost: "2" + agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" + agentPoolCredentials: + existingSecret: "my-existing-secret" + apiKey: "" + pinnedCertHash: "" + agentTags: + - env-production + - service-my-other-server + - region-us_east_1 + - provider-aws +``` + +## Uninstallation +To uninstall the chart: + +```bash +helm uninstall -n +``` +This command removes all the Kubernetes components associated with the chart and deletes the release. diff --git a/charts/lightrun-agents/templates/java-agent-cr.yaml b/charts/lightrun-agents/templates/java-agent-cr.yaml new file mode 100644 index 0000000..b53808e --- /dev/null +++ b/charts/lightrun-agents/templates/java-agent-cr.yaml @@ -0,0 +1,36 @@ +{{ range .Values.javaAgents }} +--- +apiVersion: agents.lightrun.com/v1beta +kind: LightrunJavaAgent +metadata: + name: {{ .name }} + namespace: {{ .namespace }} +spec: + initContainer: + image: {{ .initContainer.image }} + sharedVolumeName: {{ .initContainer.sharedVolumeName | default "lightrun-agent-init" }} + sharedVolumeMountPath: {{ .initContainer.sharedVolumeMountPath | default "/lightrun" }} + deploymentName: {{ .deploymentName }} + containerSelector: {{- toYaml .containerSelector | nindent 4 }} + {{- if .agentPoolCredentials.existingSecret }} + secretName: {{ .agentPoolCredentials.existingSecret }} + {{- else }} + secretName: {{ .name }}-secret + {{- end }} + serverHostname: {{ .serverHostname }} + agentEnvVarName: {{ .agentEnvVarName | default "JAVA_TOOL_OPTIONS" }} + {{- if .agentConfig }} + agentConfig: {{ toYaml .agentConfig | nindent 4 }} + {{- end }} + {{- if .agentCliFlags }} + agentCliFlags: {{ .agentCliFlags }} + {{- end }} + agentTags: + {{- range .agentTags }} + - {{. -}} + {{- end }} + {{- if .agentName }} + agentName: {{ .agentName }} + {{- end }} +{{- end }} + \ No newline at end of file diff --git a/charts/lightrun-agents/templates/secret.yaml b/charts/lightrun-agents/templates/secret.yaml new file mode 100644 index 0000000..db77543 --- /dev/null +++ b/charts/lightrun-agents/templates/secret.yaml @@ -0,0 +1,16 @@ +{{ range .Values.javaAgents }} +{{- if not .agentPoolCredentials.existingSecret }} +--- +apiVersion: v1 +metadata: + name: {{ .name }}-secret + namespace: {{ .namespace }} +stringData: + # Lightrun key you can take from the server UI at the "setup agent" step + lightrun_key: {{ .agentPoolCredentials.apiKey }} + # Server certificate hash. It is ensuring that agent is connected to the right Lightrun server + pinned_cert_hash: {{ .agentPoolCredentials.pinnedCertHash }} +kind: Secret +type: Opaque +{{- end }} +{{- end }} diff --git a/charts/lightrun-agents/values.yaml b/charts/lightrun-agents/values.yaml new file mode 100644 index 0000000..f051d1e --- /dev/null +++ b/charts/lightrun-agents/values.yaml @@ -0,0 +1,4 @@ +# Default values for lightrun-javaagent. +# This is a YAML-formatted file. +# Declare variables to be passed into your templates. +javaAgents: []