Installing a private location on a three-node cluster

Deploy private location on a three-node K3s cluster in an online or air-gapped environment.

Before you begin

Before you deploy private location on a three-node cluster, complete the following prerequisites:

Review the system requirements. See System requirements.
Prepare your environment. See Prepare environment.
Add the Instana repository and install the popctl tool on the leader node. See Deploying self-hosted Synthetic PoP with popctl For a multi-node cluster, run commands on the leader node.

The private location installer first installs a K3s cluster, and then deploys private location components on the cluster.

Procedure

Deploy private location in an online environment.

You can either create the cluster and install private location in a single command (Option 1), or create the cluster first, and then deploy private location separately (Option 2).

Option 1: Create the cluster and install private location in one command

On the leader node, run the following command:

popctl up --create-k3s-cluster --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>

Enter the required parameter values at the prompt:

? Enter PoP label(label is PoP identifier which can not be changed): synthetic-pop-prod
? Enter instana synthetic endpoint URL: https://synthetics-saas.instana.rocks
? Enter the namespace of Synthetic PoP: synthetic-pop
? Do you want to enable TLS encryption for redis communication? No
? Enter a new password for redis communication: **********
? Enter instana agent key: ************
? Enter the download key: **********************

When you successfully initialize the installation, you see the following message:

It might take several minutes for private location to be ready. When the cluster is ready, you see the following message:

Option 2: Create the cluster first, and then deploy private location

Step 1: Create the three-node K3s cluster. To create only the K3s cluster without deploying Synthetic PoP, run the following command on the leader node:

popctl cluster create --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>

For example:

popctl cluster create --multi-node-enable --multi-node-ips=10.8.1.10,10.8.1.11,10.8.1.12

Provide IP addresses in the following order: Leader node IP (instana-0), instana-1 IP, and instana-2 IP

All three nodes are available for running private location workloads. Kubernetes automatically schedules the components across the nodes based on resource availability.

Step 2: Deploy private location on the cluster

After you create the cluster, run the following command on the leader node:

popctl up --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>

Enter the required parameter values at the prompt:

? Enter PoP label(label is PoP identifier which can not be changed): synthetic-pop-prod
? Enter instana synthetic endpoint URL: https://synthetics-saas.instana.rocks
? Enter the namespace of Synthetic PoP: synthetic-pop
? Do you want to enable TLS encryption for redis communication? No
? Enter a new password for redis communication: **********
? Enter instana agent key: ************
? Enter the download key: **********************

It might take several minutes for private location to be ready. When the cluster is ready, you see the following message:

⠹ Setting up the cluster [6s] ✓
⠦ Applying synthetic-pop [1m54s] ✓
****************************************************************
* Successfully deployed Synthetic PoP on three-node cluster!   *
****************************************************************

If you are deploying in an air-gapped environment, create the air-gapped installation package on your bastion host.

In an air-gapped environment, you must create an installation package on your bastion host, transfer it to the host in the air-gapped environment, and then use the package to deploy.
1. On your bastion host, verify that you installed popctl.
2. Create the air-gapped package.
```
popctl air-gapped package
```
  By default, the system creates the package in the current directory.
3. Enter the download key to proceed with the download.
```
? Enter the download key or an official agent key: **********************
```
  If the key is valid, the installer downloads the artifacts and creates the air-gapped package:
```
⠋ 1/6 Packaging popctl artifacts [1/1]  [0s] ✓
⠋ 2/6 Packaging BuildMeta artifacts [1/1]  [0s] ✓
⠧ 3/6 Packaging Cluster artifacts [2/2]  [0s] ✓
⠼ 4/6 Packaging Helm artifacts [2/2]  [1m5s] ✓
⠙ 5/6 Packaging Registry (linux/amd64) artifacts [6/6]  [4s] ✓
⠼ 6/6 Packaging Agent (linux/amd64) artifacts [2/2]  [2s] ✓
⠸ Archiving air-gapped package  [5s] ✓
```
  Depending on network conditions, creating the package might take several minutes. When the package is ready, you see the following message:
```
------------------------------------------
Air-gapped package successfully exported!

File: synthetic-pop-airgapped.tar.gz
```
Transfer the air-gapped package from the bastion host to the leader node in your air-gapped environment.
Install popctl on the air-gapped leader node by extracting it from the air-gapped package.
Extract the popctl binary from the package and copy it to the /usr/local/bin directory on the leader node.
```
tar -xzf </path/to/synthetic-pop-airgapped.tar.gz> -C /usr/local/bin --strip-components 1 airgapped/popctl
```

Import the air-gapped package on the leader node.

popctl air-gapped import --file </path/to/synthetic-pop-airgapped.tar.gz>

Deploy private location in the air-gapped environment.

You can either create the cluster and deploy private location in a single command (Option 1), or create the cluster first, and then deploy private location separately (Option 2).

Option 1: Create the cluster and deploy private location in one command.

On the leader node, run the following command:

popctl cluster create --air-gapped --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>

Option 2: Create the cluster first, then deploy private location.

Step 1: Create the three-node K3s cluster

On the leader node, run the following command:

popctl cluster create --air-gapped --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>

Step 2: Deploy private location on the cluster

After you create the cluster, run the following command on the leader node as the user you configured for SSH access:

popctl up --air-gapped --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>

Enter the required parameter values at the prompt:

? Enter PoP label(label is PoP identifier which can not be changed): synthetic-pop-prod
? Enter instana synthetic endpoint URL: https://synthetics-saas.instana.rocks
? Enter the namespace of Synthetic PoP: synthetic-pop
? Do you want to enable TLS encryption for redis communication? No
? Enter a new password for redis communication: **********
? Enter instana agent key: ************
? Enter the download key: **********************

It might take several minutes for private location to be ready. When the cluster is ready, you see the following message:

⠹ Setting up the cluster [6s] ✓
⠦ Applying synthetic-pop [1m54s] ✓
****************************************************************
* Successfully deployed Synthetic PoP on three-node cluster!   *
****************************************************************

Install an Instana agent on the leader node to monitor private location.

You do not need to pass the --air-gapped parameter when you install the agent.

popctl agent apply

Enter the required values at the prompt. The following example shows a sample output:

? popctl will use Helm Chart to install/update Instana Agent, please uninstall the existing Instana Agent first if the agent is installed with Operator or YAML, please confirm to install agent with Helm Chart Yes

? Enter Instana Endpoint port: 443

⠴ Applying instana-agent [5s] ✓
⠋ Setting up TLS Secrets [0s] ✓
⠋ Setting up Instana Agent TLS [0s] ✓

Verify that all pods are running correctly.
Run the following command to check pod status. Replace namespace with the namespace that you specified during installation (default is synthetic-pop).
```
kubectl get pods -n <namespace>
```
All pods must be in the "running" state. If any pod is not running, check the pod logs:
```
kubectl logs -n <namespace> <pod-name>
```

Results

You deployed private location, and it is running on your three-node cluster. All pods are in the "running" state.

What to do next

After installation, you can perform the following optional tasks:

Scale the installation

Adjust the replica count for the playback engines:

popctl up --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP> \
  --set browserscript.replicas=3 \
  --set http.replicas=3 \
  --set javascript.replicas=3 \
  --set ism.replicas=3

For more information, see Capacity planning and scaling.

Upgrade private location

To upgrade to the latest version, run the popctl up command again with the same configuration.
```
popctl up --multi-node-enable --multi-node-ips=<leader-node-IP>,<instana-1-IP>,<instana-2-IP>
```
The upgrade process preserves your existing configuration and data.
Uninstall private location

To uninstall private location from the three-node cluster, run the following command on the leader node:
```
popctl down
```
A sample output:
```
? Do you want to uninstall PoP under namespace "synthetic-pop"? Yes
⠧ Uninstalling synthetic-pop from namespace synthetic-pop [0s] ✓
```
To delete the K3s cluster, run the following command. The system deletes the K3s binary file along with the cluster.
```
popctl cluster delete
```

For troubleshooting information, see Troubleshooting a three-node private location deployment.