Merge pull request #708 from arpitn2020/instana-addon-docs

Instana Addon Documentation PR

docs/addons/index.md

@@ -39,6 +39,7 @@ The framework currently supports the following add-ons.
 | [`FluxcdAddOn`](./fluxcd.md)                                   | Setting up [Fluxcd](https://fluxcd.io/) to manage one or more Kubernetes clusters.                                 | ✅ | ✅
 | [`GrafanaOperatorAddon`](./grafana-operator.md)                                   | Deploys [GrafanaOperatorAddon](https://github.com/grafana-operator/grafana-operator#:~:text=The%20grafana%2Doperator%20is%20a,an%20easy%20and%20scalable%20way)  on your EKS Cluster to manage Amazon Managed Grafana and other external Grafana instances.                                 | ✅ | ✅ |
 | [`IstioBaseAddOn`](./istio-base.md)                                  | Adds support for Istio base chart to the EKS cluster. | ✅ | ✅ |
+| [`InstanaAddOn`](./instana-addon.md)                                  | Adds the IBM® [Instana®](https://www.ibm.com/products/instana) [Agent Operator](https://github.com/instana/instana-agent-operator) to the EKS cluster. | ✅ | ✅ |
 | [`IstioControlPlaneAddOn`](./istio-control-plane.md)                | Installs Istio Control Plane addon to the EKS cluster. | ✅ | ✅ |
 | [`JupyterHubAddOn`](./jupyterhub.md)                                   | Adds [JupyterHub](https://zero-to-jupyterhub.readthedocs.io/en/latest/#) support for AWS to the cluster.                               | ✅ | ✅ |
 | [`Kasten-K10AddOn`](./kasten-k10.md)                          | Kasten K10 add-on installs Kasten K10 into your Amazon EKS cluster. | ✅ | 
@@ -161,4 +162,4 @@ HelmAddOn.failOnVersionValidation = true; // enable synth to throw exceptions on
 new blueprints.addons.MetricsServerAddOn({
     skipVersionValidation: true
 })
-```
+```

docs/addons/instana-addon.md

@@ -0,0 +1,199 @@
+# IBM® Instana® Addon for Amazon EKS Blueprints
+
+The IBM® Instana® Addon for Amazon EKS Blueprints is designed to enhance observability, monitoring, and management capabilities for applications running on Amazon Elastic Kubernetes Service (EKS). IBM Instana collects data from monitored systems by using a single agent on each host. The agent runs on your hosts to collect and aggregate data from various sensors before it sends the data to the Instana backend.
+
+The IBM® Instana® [Addon](https://www.npmjs.com/package/%40instana/aws-eks-blueprint-addon) focuses on enhancing the user experience by reducing the complexity and time required to install and configure an Instana host agent on Amazon EKS cluster. Once you configure the addon for a Amazon EKS blueprints, it will be automatically provisioned during deployment.
+
+This Addon will use IBM Instana Kubernetes operator in the namespace ```instana-agent``` to install and manage the Instana agent. It also configures custom resource values to configure the operator.
+
+## Prerequisites
+
+Ensure that you have installed the following tools on your machine.
+
+1. [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
+2. [kubectl](https://Kubernetes.io/docs/tasks/tools/)
+3. [cdk](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install)
+4. [npm](https://docs.npmjs.com/cli/v8/commands/npm-install)
+5. Instana backend application - Use SaaS (eg [aws](https://aws.amazon.com/marketplace/pp/prodview-hnqy5e3t3fzda?sr=0-1&ref_=beagle&applicationId=AWSMPContessa)) or Install self-hosted Instana backend ([on-premises](https://www.ibm.com/docs/en/instana-observability/current?topic=installing-configuring-self-hosted-instana-backend-premises))
+
+## Installation
+
+To create a new project and install dependencies, follow these steps from Amazon EKS Blueprints [Quick Start](https://aws-quickstart.github.io/cdk-eks-blueprints/getting-started)
+
+Use following command to Install IBM Instana Addon:
+
+```shell
+npm i @instana/aws-eks-blueprint-addon
+```
+
+## Instana Agent Configuration
+Go to your Instana installation (Instana User Interface), click ... More > Agents > Installing Instana Agents and select 'Kubernetes' platform to get the Instana Agent Key, Instana Service Endpoint, Instana Service port. These steps are also described [here](https://www.ibm.com/docs/en/instana-observability/218?topic=instana-endpoints-keys) or in the screenshot below.
+
+![Instana Agent Configuration](../assets/images/instana-agent.png)
+
+## AWS Secret Manager Secrets (Optional)
+If you wish to use AWS Secret Manager Secrets to pass Instana props (key, endpoint, and port), then you will be required to setup Secrets first.
+
+```shell
+export SECRET_NAME=<aws_secret_name>
+export INSTANA_AGENT_KEY=<instana_key>
+export INSTANA_ENDPOINT_HOST_URL=<instana_host_endpoint>
+export INSTANA_ENDPOINT_HOST_PORT=<instana_port>"
+aws secretsmanager create-secret \
+  --name $SECRET_NAME \
+  --secret-string "{\"INSTANA_AGENT_KEY\":\"${INSTANA_AGENT_KEY}\",
+    \"INSTANA_ENDPOINT_HOST_URL\":\"${INSTANA_ENDPOINT_HOST_URL}\",
+    \"INSTANA_ENDPOINT_HOST_PORT\":\"${INSTANA_ENDPOINT_HOST_PORT}\"
+   }"
+```
+secret_name = AWS Secret Manager Secret name (eg. *instana-secret-params*).
+
+## Usage : Using AWS Secret Manager Secrets 
+To use AWS Secret Manager Secrets follow these steps:
+
+1. The actual settings for the secret name (```secretParamName```) are expected to be specified in the CDK context. Generically it is inside the cdk.context.json file of the current directory or in `~/.cdk.json` in your home directory.
+
+	 Example settings: Update the context in `cdk.json` file located in `cdk-eks-blueprints-patterns` directory
+	 ```json
+	"context": {
+         "secretParamName": "instana-secret-params"
+     }
+    ```
+
+2. Go to project/bin/<your-main-file>.ts
+    ```typescript
+    import 'source-map-support/register';
+    import * as cdk from 'aws-cdk-lib';
+    import * as blueprints from '@aws-quickstart/eks-blueprints';
+    import { loadYaml } from '@aws-quickstart/eks-blueprints/dist/utils';
+    import { InstanaOperatorAddon } from '@instana/aws-eks-blueprint-addon';
+    
+    const app = new cdk.App();
+	const instanaSecretName = app.node.tryGetContext('<instana-secret-param>');
+    
+    export const instanaProps = {
+    	// In this example, the secret is called instana-secret-param
+        secretParamName: instanaSecretName
+    };
+    
+    const yamlObject = loadYaml(JSON.stringify(instanaProps));
+    
+    // AddOns for the cluster.
+    const addOns: Array<blueprints.ClusterAddOn> = [
+        new InstanaOperatorAddon(yamlObject)
+    ];
+    
+    const account = '<aws account id>';
+    const region = '<aws region>';
+    
+    blueprints.EksBlueprint.builder()
+        .account(account)
+        .region(region)
+        .addOns(...addOns)
+        .useDefaultSecretEncryption(true)
+        .build(app, '<eks cluster name>');
+    ```
+
+## Usage : Using Secrets in the Code
+```typescript
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import * as blueprints from '@aws-quickstart/eks-blueprints';
+import { loadYaml } from '@aws-quickstart/eks-blueprints/dist/utils';
+import { InstanaOperatorAddon } from '@instana/aws-eks-blueprint-addon';
+
+const app = new cdk.App();
+
+export const instanaProps = {
+	agent: {
+    	key: "<instana agent key>", // Mandatory Parameter
+    	endpointHost: "<instana backend host>",// Mandatory Parameter
+    	endpointPort: "<instana backend port>",// Mandatory Parameter
+	}
+};
+
+const yamlObject = loadYaml(JSON.stringify(instanaProps));
+
+// AddOns for the cluster.
+const addOns: Array<blueprints.ClusterAddOn> = [
+    new InstanaOperatorAddon(yamlObject)
+];
+
+const account = '<aws account id>';
+const region = '<aws region>';
+
+blueprints.EksBlueprint.builder()
+    .account(account)
+    .region(region)
+    .addOns(...addOns)
+    .useDefaultSecretEncryption(true)
+    .build(app, '<eks cluster name>');
+```
+
+## AddOn Configuration Options
+| Option                  | Description                                         | Default                       |
+|-------------------------|-----------------------------------------------------|-------------------------------|
+| `agent.endpointHost`                | Instana Agent backend endpoint host                                | https://ingress-red-saas.instana.io/ (US and ROW)                            |
+| `agent.endpointPort`                | Instana Agent backend endpoint port                                | "443"                            |
+| `agent.key`  | Your Instana Agent key             | nil                            |
+| `agent.downloadKey`  | Your Instana Download key             | nil                            |
+| `agent.env`       | Additional environment variables for the agent    | {}                            |
+| `agent.configuration_yaml`       | Custom content for the agent configuration.yaml file    | nil                            |
+| `cluster.name`             | Display name of the monitored cluster    | "Value of zone.name"                     |
+| `zone.name`               | Zone that detected technologies will be assigned to               | nil                     |
+
+## Bootstraping
+Bootstrap your environment with the following command.
+
+```shell
+cdk bootstrap
+```
+
+and finally you can deploy the stack with the following command.
+```shell
+cdk deploy
+```
+
+## Verify the resources
+Run update-kubeconfig command. You should be able to get the command from CDK output message. More information can be found [here](https://aws-quickstart.github.io/cdk-eks-blueprints/getting-started/#cluster-access).
+
+```console
+aws eks update-kubeconfig --name <your cluster name> --region <your region> --role-arn arn:aws:iam::xxxxxxxxx:role/eks-blue1-eksblue1AccessRole32C5DF05-1NBFCH8INI08A
+```
+
+## Testing
+To validate if Instana Agent configured properly in Amazon EKS. You can run the following command after Amazon EKS cluster in deployed and running.
+```shell
+kubectl get pods -n instana-agent
+```
+Output of the above command will be silimar to below one:
+
+```output
+NAMESPACE       NAME                                  				READY   	STATUS    RESTARTS   AGE
+instana-agent   controller-manager-78479cb596-sktg9   	1/1     	Running   					0          56m
+instana-agent   controller-manager-78479cb596-xz8kn   	1/1     	Running   					0          56m
+instana-agent   instana-agent-gsqx8                   				1/1     	Running   					0          56m
+```
+
+Run following command to verify Instana Agent logs
+```shell
+kubectl logs <instana-agent-pod-name> -n instana-agent # Output shows instana agent logs. pod name in this example is instana-agent-gsqx8
+```
+
+Once you see Instana Agent is running in your Amazon EKS Cluster, you can go to Instana Installation (User Interface) to get the APM metrices.
+
+![Instana Metrics](../assets/images/instana-metrics.png)
+
+## Cleanup
+
+To clean up your EKS Blueprints, run the following commands:
+
+```sh
+cdk destroy
+```
+
+## Disclaimer 
+This pattern relies on an open source NPM package [aws-eks-blueprint-addon](https://www.npmjs.com/package/%40instana/aws-eks-blueprint-addon). Please refer to the package npm site for more information.
+```
+https://www.npmjs.com/package/@instana/aws-eks-blueprint-addon'
+```