Skip to main content
Version: 2.8.0

Sidecar

The Aperture Agent can also be installed as a Sidecar. In this mode, whenever a new pod is started with required labels and annotations, the agent container will be attached with the pod.

Controlling the Injection Policy​

The Aperture Agent's Sidecar injection can be enabled by adding namespace labels and pod annotations as below:

ResourceLabelAnnotationEnabled ValueDisabled Value
Namespaceaperture-injection-enableddisabled
Pod-sidecar.fluxninja.com/injectiontruefalse

The injector is configured with the following logic:

  • If either label or annotation is disabled, the pod is not injected
  • If pod annotation is enabled, but the namespace label is not present, the pod is not injected
  • If you don't set the label and annotation, the system injects the sidecar if the namespace appears under .spec.sidecar.enableNamespacesByDefault. By default, this feature is disabled, so the system doesn't inject the sidecar.

Prerequisites​

You can do the installation using the aperturectl CLI tool or using Helm. Install the tool of your choice using the following links:

  1. aperturectl

    Refer

    aperturectl install agent to see all the available command line arguments.

  2. Helm

    1. Once the Helm CLI is installed, add the Aperture Agent Helm chart repository in your environment for install or upgrade:

      helm repo add aperture https://fluxninja.github.io/aperture/
      helm repo update

Installation​

The Aperture Agent in the Sidecar mode will be installed using the Kubernetes Custom Resource, which will be managed by the Aperture Operator.

By following these instructions, you will have deployed the Aperture Agent into your cluster.

Refer

Kubernetes Objects which will be created by following steps are listed here.

  1. Configure the below parameters of etcd and Prometheus for the Agent Custom Resource by creating a values.yaml with the following parameters and passing it with install command:

    agent:
      sidecar:
        enabled: true
      config:
        etcd:
          endpoints: ["ETCD_ENDPOINT_HERE"]
        prometheus:
          address: "PROMETHEUS_ADDRESS_HERE"
        agent_functions:
          endpoints: ["CONTROLLER_ENDPOINT_HERE"]

    Replace the values of ETCD_ENDPOINT_HERE and PROMETHEUS_ADDRESS_HERE with the actual values of etcd and Prometheus, which is also being used by the Aperture Controller you want these Agents to connect to. CONTROLLER_ENDPOINT_HERE should point to the Aperture Controller. If you skip it, some sub commands aperturectl commands won't work.

    If you have installed the Aperture Controller on the same cluster in default namespace, with etcd and Prometheus using controller as release name, the values for ETCD_ENDPOINT_HERE, PROMETHEUS_ADDRESS_HERE and CONTROLLER_ENDPOINT_HERE would be as below:

    agent:
      sidecar:
        enabled: true
      config:
        etcd:
          endpoints: ["http://controller-etcd.default.svc.cluster.local:2379"]
        prometheus:
          address: "http://controller-prometheus-server.default.svc.cluster.local:80"
        agent_functions:
          endpoints: ["aperture-controller.default.svc.cluster.local:8080"]
    aperturectl install agent --version v2.8.0 --values-file values.yaml

  2. To enable the pod injection for a list of namespaces by default, you can create or update the values.yaml file and pass it with the install command:

    agent:
      sidecar:
        enabled: true
        enableNamespacesByDefault:
          - NAMESPACE1
          - NAMESPACE2
      config:
        etcd:
          endpoints: ["http://controller-etcd.default.svc.cluster.local:2379"]
        prometheus:
          address: "http://controller-prometheus-server.default.svc.cluster.local:80"

    Replace the NAMESPACE1, NAMESPACE2 and other namespaces, with the actual namespaces and add more if required.

    aperturectl install agent --version v2.8.0 --values-file values.yaml

  3. If you want to modify the default parameters or the Aperture Agent configuration, for example log, you can create or update the values.yaml file and pass it with install command:

    agent:
      sidecar:
        enabled: true
      config:
        etcd:
          endpoints: ["ETCD_ENDPOINT_HERE"]
        prometheus:
          address: "PROMETHEUS_ADDRESS_HERE"
        log:
          level: debug
          pretty_console: true
          non_blocking: false
    aperturectl install agent --version v2.8.0 --values-file values.yaml

    All the configuration parameters for the Aperture Agent are available here.

    A list of configurable parameters for the installation can be found in the README.

  4. If you want to deploy the Aperture Agent into a namespace other than default, use the --namespace flag:

    aperturectl install agent --version v2.8.0 --values-file values.yaml --namespace aperture-agent

  5. Alternatively, you can create the Agent Custom Resource directly on the Kubernetes cluster using the below steps:

    1. Create a values.yaml for just starting the operator and disabling the creation of Agent Custom Resource and pass it with install command:

      agent:
        create: false
      aperturectl install agent --version v2.8.0 --values-file values.yaml

    2. Create a YAML file with the following specifications:

      apiVersion: fluxninja.com/v1alpha1
      kind: Agent
      metadata:
        name: agent
      spec:
        sidecar:
          enabled: true
        config:
          etcd:
            endpoints: ["ETCD_ENDPOINT_HERE"]
          prometheus:
            address: "PROMETHEUS_ADDRESS_HERE"

      Replace the values of ETCD_ENDPOINT_HERE and PROMETHEUS_ADDRESS_HERE with the actual values of etcd and Prometheus, which is also being used by the Aperture Controller you want these Agents to connect to.

      All the configuration parameters for the Agent Custom Resource are listed on the README file of the Helm chart.

    3. Apply the YAML file to Kubernetes cluster using kubectl

      kubectl apply -f agent.yaml

  6. Refer to the steps on the Istio Configuration if you do not have the Envoy Filter configured on your cluster.

Upgrade Procedure​

By following these instructions, you will have deployed the upgraded version of Aperture Agent into your cluster.

  1. Use the same values.yaml file created as part of the Installation Steps and pass it with below command:

    aperturectl install agent --version v2.8.0 --values-file values.yaml

  2. If you have deployed the Aperture Agent into a namespace other than default, use the --namespace flag:

    aperturectl install agent --version v2.8.0 --values-file values.yaml --namespace aperture-agent

Verifying the Installation​

Once you have successfully deployed the resources, confirm that the Aperture Agent is up and running:

kubectl get pod -A

kubectl get agent -A

You should see pod for Aperture Agent Manager in RUNNING state and Agent Custom Resource in created state.

Now, when you create a new pod in the above listed namespaces, you will be able to see the Aperture Agent container attached with the existing pod containers. Confirm that the container is injected:

kubectl describe po <POD_ID>

Replace the POD_ID with the actual pod ID and check the containers section in the output. There should be a container with the name aperture-agent.

Customizing injection​

The pods are injected based on the default and overridden parameters provided in the Custom Resource.

Per-pod configuration is available to override these options on individual pods. This is done by adding a aperture-agent container to your pod. The sidecar injection will treat any configuration defined here as an override to the default injection template.

Care should be taken when customizing these settings, as this allows complete customization of the resulting Pod, including making changes that might affect the sidecar container's functionality.

For example, the following configuration customizes a variety of settings, including setting the CPU requests, adding a volume mount, and modifying environment variables:

apiVersion: v1
kind: Pod
metadata:
  labels:
    run: nginx
  name: nginx
spec:
  containers:
    - name: aperture-agent
      image: auto
      env:
        - name: "APERTURE_AGENT_AGENT_INFO_AGENT_GROUP"
          value: "group1"
      resources:
        requests:
          cpu: 1
          memory: 256Mi
    - image: nginx
      name: nginx
      resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always

In general, any field in a pod can be set. However, care must be taken in certain fields:

  • Kubernetes requires the image field to be set before the injection has run. While you can set a specific image to override the default one, it is recommended to set the image to auto, which will cause the sidecar injector to automatically select the image to use.
  • Some fields in Pod are dependent on related settings. For example, CPU request must be less than the CPU limit. If both fields aren't configured together, the pod might fail to start.

Additionally, the agent-group field can be configured using the annotation like:

sidecar.fluxninja.com/agent-group=group1

Uninstall​

You can uninstall the Aperture Agent and its components installed above by following these steps:

  1. Delete the Aperture Agent chart:

    aperturectl uninstall agent --version v2.8.0

  2. If you have installed the Aperture Agent Custom Resource, follow the steps below:

    1. Delete the Aperture Agent Custom Resource:

      kubectl delete -f agent.yaml

    2. Delete the Aperture Agent to uninstall the Aperture Operator:

      aperturectl uninstall agent --version v2.8.0

  3. If you have installed the chart in some other namespace than the default, execute the following commands:

    aperturectl uninstall agent --namespace aperture-agent --version v2.8.0

  4. Restarts all the Pods which were injected with the Sidecar:

  5. If pods are running as part of a Kubernetes Deployment:

    kubectl rollout restart deployment <DEPLOYMENT_NAME> -n <NAMESPACE>

  6. If pods are running as part of a Kubernetes DaemonSet:

    kubectl rollout restart daemonset <DAEMONSET_NAME> -n <NAMESPACE>

  7. If pod is running standalone (not part of a deployment or replica set):

    kubectl delete pod <POD_ID> -n <NAMESPACE>
    k apply -f pod.yaml

  8. By default, the Secret having SSL/TLS certificates generated by the Kubernetes Operator for itself is not deleted with above steps. If you want to delete it, run the below commands:

    kubectl delete secret -l app.kubernetes.io/instance=agent-aperture-agent-manager

  9. Optional: Delete the CRD installed by the Helm chart:

    note

    Deleting a Helm chart using Helm does not delete the Custom Resource Definitions (CRD) installed from the chart.

    kubectl delete crd agents.fluxninja.com