Update documentation with statefulset

Author: eliranb

config/samples/agents_v1beta_lightrunjavaagent.yaml

@@ -7,7 +7,9 @@ spec:
     image: "lightruncom/k8s-operator-init-java-agent-linux:1.7.0-init.0"
     sharedVolumeName: lightrun-agent-init
     sharedVolumeMountPath: "/lightrun"
-  deploymentName: app  
+  # Specify either deploymentName OR statefulSetName, not both
+  deploymentName: app  # Use this for Deployments
+  #statefulSetName: app-stateful  # Use this for StatefulSets
   secretName: lightrun-secrets 
   serverHostname: <lightrun_server>  #for saas it will be app.lightrun.com
   agentEnvVarName: JAVA_TOOL_OPTIONS

docs/README.md

@@ -1,10 +1,10 @@
 ### Important to know before deploying to production  
 
   - `LightrunJavaAgent` Customer resource hardly dependent on the secret with `lightrun_key` and `pinned_cert_hash` values. It has do be deployed in the same namespace as the secret.
-  - `LightrunJavaAgent` CR has to be installed in the same namespace as deployment
-  - You need to create `LightrunJavaAgent` CR per deployment that you want to patch
-  - When `creating or deleting CR`, deployment will trigger `recreation of all the pods`, as Pod Template Spec will be changed
-  - If, for some reason, your cluster will not be able to `download init container` images from https://hub.docker.com/, your deployment will stuck in this state until it won't be resolved. This is the limitation of the init containers
+  - `LightrunJavaAgent` CR has to be installed in the same namespace as the target resource (Deployment or StatefulSet)
+  - You need to create `LightrunJavaAgent` CR per resource (Deployment or StatefulSet) that you want to patch
+  - When `creating or deleting CR`, the target resource will trigger `recreation of all the pods`, as Pod Template Spec will be changed
+  - If, for some reason, your cluster will not be able to `download init container` images from https://hub.docker.com/, your target resource will stuck in this state until it won't be resolved. This is the limitation of the init containers
   - If you will change `secret` values, `agentConfig` or `agentTags`, operator will update Config Map with that data and trigger recreation of the pods to apply new config of the agent
   - Always check `release notes` before upgrading the operator. If CRD fields was changed you'll need to act accordingly during the upgrade 
   - You can't have `duplicate ENV` variable in the container spec. 
@@ -17,4 +17,14 @@
         name: <Your deployment name>
         jqPathExpressions:
         - '.spec.template.spec.containers[] | select(.name == "<your container name>").env[] | select(.name == "JAVA_TOOL_OPTIONS")' 
+  ```
+  
+  For StatefulSets, use:
+  ```yaml
+      ignoreDifferences:
+      - group: apps
+        kind: StatefulSet
+        name: <Your statefulset name>
+        jqPathExpressions:
+        - '.spec.template.spec.containers[] | select(.name == "<your container name>").env[] | select(.name == "JAVA_TOOL_OPTIONS")' 
   ```

docs/before_prod.md

@@ -16,9 +16,13 @@ spec:
     # Mount path where volume will be parked. Various distributions may have it's limitations.
     # For example you can't mount volumes to any path except `/tmp` when using AWS Fargate
     sharedVolumeMountPath: "/lightrun"
+  # NOTE: Specify either deploymentName OR statefulSetName, not both
   # Name of the deployment that you are going to patch.
   # Has to be in the same namespace
   deploymentName: app  
+  # Name of the statefulset that you are going to patch.
+  # Has to be in the same namespace
+  # statefulSetName: app-stateful
   # Name of the secret where agent will take `lightrun_key` and `pinned_cert_hash` from
   # Has to be in the same namespace
   secretName: lightrun-secrets 
@@ -54,5 +58,4 @@ stringData:
   # Server certificate hash. It is ensuring that agent is connected to the right Lightrun server
   pinned_cert_hash: <pinned_cert_hash>
 kind: Secret
-type: Opaque
-```
+type: Opaque

docs/custom_resource.md

@@ -7,14 +7,14 @@
    (subject to how it's been installed). 
  Every event related to these CRs triggers the reconcile loop of the controller. You can find logic of this loop [here](reconcile_loop.excalidraw.png)  
  - When triggered, the controller performs several actions:
-   - Check if it has access to deployment
+   - Check if it has access to the target resource (Deployment or StatefulSet)
    - Fetch data from the CR secret
    - Create config map with agent config from CR data
-   - Patch the deployment:
+   - Patch the target resource (Deployment or StatefulSet):
      - insert init container
      - add volume
      - map that volume to the specified container
      - add/update specified ENV variable in order to let Java know where agent files are found (the mapped volume)
- - After deployment is patched, k8s will `recreate all the pods` in the deployment. New Pods will be initialized with the Lightrun agent
- - If user deletes the `LightrunJavaAgent` CR, the Controller will roll back all the changes to deployment. This will trigger `recreation of all pods` again
+ - After the target resource is patched, k8s will `recreate all the pods` in the Deployment or StatefulSet. New Pods will be initialized with the Lightrun agent
+ - If user deletes the `LightrunJavaAgent` CR, the Controller will roll back all the changes to the target resource. This will trigger `recreation of all pods` again
  - [High level diagram](resource_relations.excalidraw.png) of resources created/edited by the operator

docs/how.md

@@ -19,7 +19,7 @@ spec:
           env:
             - name: JAVA_TOOL_OPTIONS
               value: -Djava.net.preferIPv4Stack=true
-          image: lightrun-k8s-operator-registry:5000/operator-demo-app:latest
+          image: lightruncom/operator-demo-app
           securityContext:
             allowPrivilegeEscalation: false
             capabilities:

examples/deployment.yaml

@@ -0,0 +1,11 @@
+---
+apiVersion: v1
+metadata:
+  name: lightrun-secrets
+stringData:
+  # Lightrun key you can take from the server UI at the "setup agent" step
+  lightrun_key: <lightrun_key>
+  # Server certificate hash. It is ensuring that agent is connected to the right Lightrun server
+  pinned_cert_hash: <pinned_cert_hash>
+kind: Secret
+type: Opaque

examples/lightrun-secret.yaml

@@ -1,7 +1,7 @@
 apiVersion: agents.lightrun.com/v1beta
 kind: LightrunJavaAgent
 metadata:
-  name: example-cr
+  name: example-deployment-cr
 spec:
   ###############################################################################################
   # Fields that you need to change if you want to try operator with your own deployment
@@ -30,7 +30,7 @@ spec:
     # agent version - first part of the tag (1.7.0)
     # init container sub-version - last part of the tag (init.0)
     # List of available images in the README.md
-    image: "lightrun-k8s-operator-registry:5000/lightrun-init-agent:latest"
+    image: "lightruncom/k8s-operator-init-java-agent-linux:latest"
     # Volume name in case you have some convention in the names
     sharedVolumeName: lightrun-agent-init
     # Mount path where volume will be parked. Various distributions may have it's limitations.
@@ -59,15 +59,3 @@ spec:
     - latest
   # Agent name. If not provided, pod name will be used
   #agentName: "operator-test-agent"
-
----
-apiVersion: v1
-metadata:
-  name: lightrun-secrets
-stringData:
-  # Lightrun key you can take from the server UI at the "setup agent" step
-  lightrun_key: 65cf112e-03f5-42da-a2f3-3c46d368872b
-  # Server certificate hash. It is ensuring that agent is connected to the right Lightrun server
-  pinned_cert_hash: ee80811b38e7e6c2dc4cc372cbea86bd86b446b012e427f2e19bf094afba5d12
-kind: Secret
-type: Opaque

examples/lightrunjavaagent.yaml

@@ -1,32 +1,60 @@
 apiVersion: agents.lightrun.com/v1beta
 kind: LightrunJavaAgent
 metadata:
-  name: statefulset-agent
+  name: example-statefulset-cr
 spec:
-  # Specify the StatefulSet to instrument
+  ###############################################################################################
+  # Fields that you need to change if you want to try operator with your own statefulset
+  ###############################################################################################
+  # Name of the statefulset that you are going to patch.
+  # Has to be in the same namespace
   statefulSetName: "sample-statefulset"
-  # List of container names inside the pod to instrument
+  # List of container names inside the pod of the statefulset
+  # If container not mentioned here it will be not patched
   containerSelector:
     - app
-  # Init container with the Lightrun agent
+  # Agent config will override  default configuration with provided values
+  # You can find list of available options here https://docs.lightrun.com/jvm/agent-configuration/
+  agentEnvVarName: "JAVA_TOOL_OPTIONS"
+  # Name of the secret where agent will take `lightrun_key` and `pinned_cert_hash` from
+  # Has to be in the same namespace
+  secretName: lightrun-secrets
+
+  ###############################################################################################
+  # Fields that are mostly fine with default values for most deployments
+  ###############################################################################################
+  # Init container with agent. Differes by agent version and platform that it will be used for. For now supported platforms are `linux` and `alpine`  
   initContainer:
-    image: "lightrun-k8s-operator-registry:5000/lightrun-init-agent:latest"
+    # parts that may vary here are
+    # platform - `linux/alpine`
+    # agent version - first part of the tag (1.7.0)
+    # init container sub-version - last part of the tag (init.0)
+    # List of available images in the README.md
+    image: "lightruncom/k8s-operator-init-java-agent-linux:latest"
+    # Volume name in case you have some convention in the names
     sharedVolumeName: "lightrun-agent"
     sharedVolumeMountPath: "/lightrun"
-  # Reference to the Secret with Lightrun credentials
-  secretName: "lightrun-secrets"
-  # Environment variable to patch with the agent path
-  agentEnvVarName: "JAVA_TOOL_OPTIONS"
-  # Lightrun server hostname
-  serverHostname: "app.lightrun.com"
-  # Optional agent configuration
+  # Hostname of the server. Will be different for on-prem ans single-tenant installations
+  # For saas it is app.lightrun.com
+  serverHostname: app.lightrun.com
+  # Env var that will be patched with agent path.
+  # If your application not using any, recommended option is to use "JAVA_TOOL_OPTIONS"
+  # Also may be "_JAVA_OPTIONS", "JAVA_OPTS"
+  # There are also different variations if using Maven -  "MAVEN_OPTS", and so on
+  # You can find more info here: https://docs.lightrun.com/jvm/agent/
   agentConfig:
     max_log_cpu_cost: "2"
-  # Tags that will appear in the Lightrun UI
+  # agentCliFlags is used if need to pass additional flags to the agent,
+  # that are not part of configuration file.
+  # https://docs.lightrun.com/jvm/agent-configuration/#additional-command-line-flags
+  # Example below
+  # agentCliFlags: --lightrun_extra_class_path=<PATH_TO_JAR>:<PATH_TO_JAR>,lightrun_init_wait_time_ms
+
+  # Tags that agent will be using. You'll see them in the UI and in the IDE plugin as well
   agentTags:
     - operator
     - example
     - latest
     - statefulset
-  # Optional agent name (if not set, pod name will be used)
-  agentName: "stateful-java-app" 
+  # Agent name. If not provided, pod name will be used
+  #agentName: "operator-test-agent"

examples/statefulset-lightrunjavaagent.yaml

@@ -19,8 +19,8 @@ spec:
         - name: app
           env:
             - name: JAVA_TOOL_OPTIONS
-              value: -Djava.net.preferIPv4Stack=true
-          image: lightrun-k8s-operator-registry:5000/operator-demo-app:latest
+              value: -Djava.net.preferIPv4Stack=true, -Xmx1024m
+          image: lightruncom/operator-demo-app
           securityContext:
             allowPrivilegeEscalation: false
             capabilities: