Using Agent Installation Command (For Agent to Be Deployed in AKS Cluster)

1. After you save your configured agent on the Calibo Accelerate Orchestrator Agents screen, click the ellipsis (...) to view the agent details. On the Agent Details side drawer, you see the following Agent Installation Command. With this command, you can install the Calibo Accelerate Orchestrator Agent and register it with the Calibo Accelerate platform.

   

2. Copy the command.

3. Replace the placeholder value of the env.AKS_MANAGED_IDENTITY_CLIENT_ID parameter with the actual value of your your client ID for the managed identity in Azure Kubernetes Service (AKS). This managed identity is generated with the agent pool name when you create an AKS cluster in the prerequisites for agent installation.

4. You have created the CA (Certificate Authority) certificate file (ca.crt), server certificate file (server.crt), and server certificate key file (server.key) in the prerequisites for agent installation. Run the command in your command line interface from the directory or folder where these TLS certificates are stored.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
helm repo add lazsa-agent https://lazsa-agent.s3.amazonaws.com/stable/lazsa-agent/ && \
helm repo update && \
helm upgrade --install lazsa-agent lazsa-agent/lazsa-agent --version=<Orchestrator Agent version> \
--set ingress.host=<Orchestrator Agent domain> --set env.api_key=<Key> \
--set env.lazsa_url=<Lazsa URL> --set env.agent_id=<Orchestrator Agent ID> --set env.tenant_id=<Tenant ID> \
--set ingress.mtls=true --set env.CLOUD_PROVIDER=AZURE \
--create-namespace --set imageCredentials.username=<Image registry username> --set imageCredentials.password=<Image registry password> \
--set secret.ca_cert_file="$(cat ca.crt)" \
--set secret.server_cert_file="$(cat server.crt)" \
--set secret.server_cert_key_file="$(cat server.key)" \
--set env.API_KEY_SECRET_NAME=<API_KEY_SECRET_NAME> \
--set namespace=<lazsa-agent-[Agent number]> -n <lazsa-agent-[Agent number]> \
--set env.vault_name=<Vault name> \
--set serviceAccountName=default \
--set env.AKS_MANAGED_IDENTITY_CLIENT_ID=<AKS_MANAGED_IDENTITY_CLIENT_ID>

Command Parameters

Let us understand what each parameter in this Helm command means. All the parameters listed in the following table are mandatory parameters.

Parameter	Meaning
ingress.host	This is the DNS address (without http or https) for your Ingress, where the Orchestrator endpoint is accessible.
env.api_key	This is an automatically generated API key for agent authentication. This key is used to register the Orchestrator Agent with the Calibo Accelerate platform.
env.lazsa_url	This is the URL of the Calibo Accelerate platform.
env.agent_id	This is an automatically generated unique ID for the Calibo Accelerate Orchestrator Agent.
env.tenant_id	This is the unique identifier of your Calibo Accelerate tenant.
ingress.mtls	This Boolean parameter is used to decide whether you want to use mTLS or not. For agent to be deployed in an AKS cluster, the value of this parameter is set to "true".
env.CLOUD_PROVIDER	This is the cloud service provider that you select while adding an agent to the Calibo Accelerate Orchestrator Agents screen. For the agent that needs to be installed in an AKS cluster, the cloud provider is AZURE.
imageCredentials.username	This is the image registry username required for pulling the agent images.
imageCredentials.password	Image registry password required for pulling the agent images.
Parameters related to TLS certificate files Note: If the CA (Certificate Authority) certificate file (ca.crt), server certificate file (server.crt), and server certificate key file (server.key) are stored in different directories or folders on your file system, provide the absolute path to each of these files. You create these certificates as part of the prerequisites for deploying an Orchestrator Agent in an Amazon EKS cluster. Note: Ensure that the names and paths of the TLS certificates are mentioned correctly in the command.	secret.ca_cert_file This is the path of the CA (Certificate Authority) certificate file (ca.crt), which is used for creating TLS secret for agent DNS. This secret is used to attach the certificate to the Ingress object. The CA certificate is used to validate the server certificate during the SSL/TLS handshake. secret.server_cert_file This is the path of the server certificate file (server.crt), which is used for creating TLS secret for agent DNS. This secret is used to attach the certificate to the Ingress object. The server certificate is used to establish a secure connection between the client and the server. secret.server_cert_key_file This is the path of the server certificate key file (server.key), which is used for creating TLS secret for agent DNS. This secret is used to attach the certificate to the Ingress object. The server certificate key is a private key that pairs with the server certificate and is used to decrypt data sent by the client during the SSL/TLS handshake.
env.API_KEY_SECRET_NAME	Replace the placeholder value with the name of the secret that you created in Azure Key Vault as one of the prerequisites for agent installation. In this secret, the Calibo Accelerate Orchestrator Agent stores and updates its API key, which is used to authenticate the agent during registration with the Calibo Accelerate platform. For more information, see API Key Validation for Calibo Accelerate Orchestrator Agent.
namespace	This creates a Kubernetes namespace where Calibo Accelerate Orchestrator Agent gets installed. By default, the lazsa-agent-<agent number> namespace is created. If you want to use any other namespace, ensure all the required resources are associated with the same namespace.
env.vault_name	This is the name of the vault in Azure Key Vault where you stored the placeholder secret as one of the prerequisites for agent installation.
serviceAccountName	This is the service account name of the Kubernetes namespace where Calibo Accelerate Orchestrator Agent is installed. The default value is 'default'.
env.AKS_MANAGED_IDENTITY_CLIENT_ID	Specify the client ID for the managed identity in Azure Kubernetes Service (AKS).

Additionally, you can use the following optional parameters in the agent installation command as per your requirements.

Parameter	Meaning
env.PROXY_HOST	This is the proxy host address (without http/https/port). It is required if your environment requires a proxy for outbound / inbound connection.
env.PROXY_PORT	This is the proxy port. It is required if your environment requires a proxy for outbound / inbound connection.
env.NON_PROXY_HOST	This is a list of domains that you want to exclude from the proxy. The list is separated by '|'. For example, 'test.calibo.com|.calibo.com|amazon.com' If proxy is enabled, it is mandatory to add the following host. Copy --set env.NON_PROXY_HOST='lazsa-management-agent-entrypoint' Any other host should be appended to the lazsa-management-agent-entrypoint host separated by '|'. Note: The lazsa-management-agent-entrypoint is the internal host within the cluster.
env.PROXY_USER	This is the username for the proxy server if it is password-protected.
env.PROXY_PASSWORD	This is the password for the proxy server.
env.API_KEY_CRON	This is the cron expression for the API key rotation. When the value is not provided, it is set to default: '0 0 1 * * SUN' which means a fresh API key will be generated every Sunday at 01.00 AM. Note: This value must be enclosed in single quotation marks. For more information, see API Key Validation for Calibo Accelerate Orchestrator Agent.
certs.RootCertFileName	This is the file name of your private / self-signed root CA certificate. This is required if you use private CA certificates for your CI/CD tools URLs.
certs.CertChainFileName	This is the file name of your private / self-signed CA certificate chain. This is required if you use private CA certificates for your CI/CD tools URLs.
certs.ServerCertFileName	This is the file name of your private / self-signed server certificate. This is required if you use private CA certificates for your CI/CD tools URLs.
env.log_level	This is to set the agent logs level. The default value is 'INFO.'
components.managementAgent	This is a Boolean parameter with the default value set to 'true.'
securityContext.readOnlyRootFilesystem	This is a Boolean parameter with the default value set to 'true.' Set it to false if you use private CA certificates for your CI/CD tools URLs.

API Key Validation for Calibo Accelerate Orchestrator Agent

In addition to the mTLS communication method, API key validation is also used to authenticate the communication between the Calibo Accelerate platform and the Calibo Accelerate Orchestrator Agent.

Before you deploy the Calibo Accelerate Orchestrator Agent to the configured AKS cluster, you must grant permissions to your AKS agentpool managed identity to read secrets from Azure Key Vault and to update the API key after it is regenerated as per your schedule.

Every REST API call going from the Calibo Accelerate platform to the Orchestrator Agent contains an API key in the header. This API key is generated by the platform during the agent registration process. The Orchestrator Agent stores this API key in the AWS Secrets Manager and uses it for validating the API requests coming from the Calibo Accelerate platform.

As a security best practice, the API key must be regenerated periodically. In the agent installation command mentioned earlier in this topic, you can provide a cron expression in the value of the env.API_KEY_CRON parameter. This value schedules the API key regeneration. If you do not provide any value for this parameter, 0 0 18 * * THU is considered as the default value for the cron job. This means a fresh API key is generated every Thursday at 06.00 PM.

The API key is stored in Azure Key Vault at the path that you specify in the value of the env.API_KEY_SECRET_PATH parameter in the Helm command.

About Cron Expressions

A cron expression consists of six or seven sub-expressions (fields) that describe details of a schedule. These sub-expressions, delimited by spaces, can accommodate a range of values and character combinations permissible for each field. Here's a breakdown of the cron fields in the prescribed sequence, along with their permissible values:

Rules for Cron Expressions

Follow these rules while using a cron expression:

• Use an asterisk (*) in a field to denote 'first-last.' This means that it matches every possible value for that field. For example, if you have an asterisk in the Day-of-month field, it will match all days of the month. For the Day-of-month field or the Day-of-week field, you can also use a question mark (?) instead of an asterisk.

• Use commas (,) to separate the items in a list. For example, to schedule a job for every Monday and Tuesday, list these days separated by commas: MON, TUE.

• Two numbers separated by a hyphen (-) express a range of numbers. The specified range is inclusive. For example, to schedule a job for every day between the 8th and 10th of the month, use the range 8-10 in the Day-of-month field.

• Following a range (or *) with a forward slash (/) specifies the interval of the number’s value through the range. For example, to schedule a job every 30 minutes between 8:00 AM and 10:00 AM, you can use 0 0/30 8-10 * * *.

• English names can also be used for the Day-of-month and Day-of-week fields. Use the first three letters of a day or a month (case does not matter). For example, if you want to schedule a job for every Monday, you can use MON in the Day-of-week field.

Examples

Let us look at some more examples of cron expressions: