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:
Resource | Label | Annotation | Enabled Value | Disabled Value |
---|---|---|---|---|
Namespace | aperture-injection | - | enabled | disabled |
Pod | - | sidecar.fluxninja.com/injection | true | false |
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:
- Refer
aperturectl install agent to see all the available command line arguments.
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.
Kubernetes Objects which will be created by following steps are listed here.
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 withinstall
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
andPROMETHEUS_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 commandsaperturectl
commands won't work.If you have installed the Aperture Controller on the same cluster in
default
namespace, with etcd and Prometheus usingcontroller
as release name, the values for the values forETCD_ENDPOINT_HERE
,PROMETHEUS_ADDRESS_HERE
andCONTROLLER_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
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml
helm install agent aperture/aperture-agent -f values.yaml
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 theinstall
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
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml
helm install agent aperture/aperture-agent -f values.yaml
If you want to modify the default parameters or the Aperture Agent configuration, for example
log
, you can create or update thevalues.yaml
file and pass it withinstall
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
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml
helm install agent aperture/aperture-agent -f 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.
If you want to deploy the Aperture Agent into a namespace other than
default
, use the--namespace
flag:- aperturectl
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml --namespace aperture-agent
helm install agent aperture/aperture-agent -f values.yaml --namespacen aperture-agent --create-namespace
Alternatively, you can create the Agent Custom Resource directly on the Kubernetes cluster using the below steps:
Create a
values.yaml
for just starting the operator and disabling the creation of Agent Custom Resource and pass it withinstall
command:agent:
create: false- aperturectl
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml
helm install agent aperture/aperture-agent -f values.yaml
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
andPROMETHEUS_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.
Apply the YAML file to Kubernetes cluster using
kubectl
kubectl apply -f agent.yaml
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.
Use the same
values.yaml
file created as part of the Installation Steps and pass it with below command:- aperturectl
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml
helm template --include-crds --no-hooks agent aperture/aperture-agent -f values.yaml | kubectl apply -f -
Once all the pods are in a running state after upgrade, run the below command to keep the Helm release updated:
helm upgrade agent aperture/aperture-agent -f values.yaml
If you have deployed the Aperture Agent into a namespace other than
default
, use the--namespace
flag:- aperturectl
- Helm
aperturectl install agent --version v2.6.0 --values-file values.yaml --namespace aperture-agent
helm template --include-crds --no-hooks agent aperture/aperture-agent -f values.yaml --namespace aperture-agent | kubectl apply -f -
Once all the pods are in a running state after upgrade, run the below command to keep the Helm release updated:
helm upgrade agent aperture/aperture-agent -f 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:
Delete the Aperture Agent chart:
- aperturectl
- Helm
aperturectl uninstall agent --version v2.6.0
helm uninstall agent
If you have installed the Aperture Agent Custom Resource, follow the steps below:
Delete the Aperture Agent Custom Resource:
kubectl delete -f agent.yaml
Delete the Aperture Agent to uninstall the Aperture Operator:
- aperturectl
- Helm
aperturectl uninstall agent --version v2.6.0
helm uninstall agent
If you have installed the chart in some other namespace than the
default
, execute the following commands:- aperturectl
- Helm
aperturectl uninstall agent --namespace aperture-agent --version v2.6.0
helm uninstall agent --namespace aperture-agent
kubectl delete namespace aperture-agentRestarts all the Pods which were injected with the Sidecar:
If pods are running as part of a Kubernetes Deployment:
kubectl rollout restart deployment <DEPLOYMENT_NAME> -n <NAMESPACE>
If pods are running as part of a Kubernetes DaemonSet:
kubectl rollout restart daemonset <DAEMONSET_NAME> -n <NAMESPACE>
If pod is running standalone (not part of a deployment or replica set):
kubectl delete pod <POD_ID> -n <NAMESPACE>
k apply -f pod.yamlBy 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
Optional: Delete the CRD installed by the Helm chart:
noteDeleting a Helm chart using Helm does not delete the Custom Resource Definitions (CRD) installed from the chart.
kubectl delete crd agents.fluxninja.com