Installing Instana backend and data stores

Adding Instana repository

Add the Instana repository to the sources.list file on your host so that the host has access to the Instana installation package.

As a root user on your host, run the following commands to add the repository:

In the following command, replace <download_key> with the download key that you got with your license. For more information, see Purchasing a license.

• If you have an Ubuntu or Debian host, run these commands:

  export DOWNLOAD_KEY=<download_key>
  
  echo 'deb [signed-by=/usr/share/keyrings/instana-archive-keyring.gpg] https://artifact-public.instana.io/artifactory/rel-debian-public-virtual generic main' > /etc/apt/sources.list.d/instana-product.list
  
  cat << EOF > /etc/apt/auth.conf
  machine artifact-public.instana.io
    login _
    password $DOWNLOAD_KEY
  EOF
  
  wget -nv -O- --user=_ --password="$DOWNLOAD_KEY" https://artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-debian-public-virtual | gpg --dearmor > /usr/share/keyrings/instana-archive-keyring.gpg
  

• If you have a Red Hat® Enterprise Linux®, CentOS Stream, Amazon Linux, or Oracle Linux host, run these commands:

  export DOWNLOAD_KEY=<download_key>
  
  cat << EOF > /etc/yum.repos.d/Instana-Product.repo
  [instana-product]
  name=Instana-Product
  baseurl=https://_:$DOWNLOAD_KEY@artifact-public.instana.io/artifactory/rel-rpm-public-virtual/
  enabled=1
  gpgcheck=0
  gpgkey=https://_:$DOWNLOAD_KEY@artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-rpm-public-virtual
  repo_gpgcheck=1
  EOF
  

• If you have a SUSE Linux Enterprise Server (SLES) host, run these commands:

  export DOWNLOAD_KEY=<download_key>
  cat << EOF > /etc/zypp/credentials.d/instana_auth
  username=_
  password=$DOWNLOAD_KEY
  EOF
  cat << EOF > /etc/zypp/repos.d/Instana-Product.repo
  [instana-product]
  name=Instana-Product
  baseurl=https://artifact-public.instana.io/artifactory/rel-rpm-public-virtual/?credentials=instana_auth
  enabled=1
  gpgcheck=0
  gpgkey=https://artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-rpm-public-virtual?credentials=instana_auth
  repo_gpgcheck=1
  EOF
  

Mirroring the repositories

Mirror the following repositories as required:

• If you want to mirror the Docker registry, mirror the following repository:

  https://artifact-public.instana.io/artifactory/rel-docker-public-virtual
  

• If you want to mirror the Helm repository, mirror the following repository:

  https://artifact-public.instana.io/artifactory/rel-helm-customer-virtual
  

• If you want to mirror cluster artifacts, mirror the following repository:

  https://artifact-public.instana.io/artifactory/rel-generic-instana-virtual/k3s-io/k3s/releases/download
  

Then, on your bastion host, install the stanctl command-line tool.

Installing stanctl command-line tool

The Standard Edition is managed by a command-line tool named stanctl that you must install.

• If you have an Ubuntu or Debian host, run these commands:

  1. Update the package index files on your host.

     apt update -y
     

  2. Install stanctl.

     apt install -y stanctl
     

  3. To avoid automatic updates, set the stanctl package version.

     apt-mark hold stanctl
     

• If you have a Red Hat Enterprise Linux or CentOS Stream host, run these commands:

  1. Refresh your yum repositories.

     yum clean expire-cache -y
     

  2. Update the package index files on your host.

     yum update -y
     

  3. Install stanctl.

     yum install -y stanctl
     

  4. If the versionlock plug-in is not installed on your host, run the following command to install the plug-in.

     yum install python3-dnf-plugin-versionlock
     

  5. To avoid automatic updates, set the stanctl package version.

     yum versionlock add stanctl
     

• If you have an Amazon Linux or Oracle Linux host, run these commands:

  1. Refresh your dnf repositories.

     dnf clean expire-cache -y
     

  2. Update the package index files on your host.

     dnf update -y
     

  3. Install stanctl.

     dnf install -y stanctl
     

  4. To avoid automatic updates, set the stanctl package version.

     dnf versionlock add stanctl
     

• If you have an SLES host, run these commands:

  1. Refresh and update the package index files on your host.

     zypper refresh
     

     Enter a, which means trust always, when you see the question Do you want to reject the key, trust temporarily, or trust always? [r/t/a/?] (r):

  2. Install stanctl.

     zypper install -y stanctl
     

After you install the tool, it is automatically added to your $PATH. You can run the stanctl commands from any directory.

To check the version of stanctl that you installed, run the following command:

stanctl --version

For more information about stanctl commands, see Using stanctl commands.

Creating the air-gapped installation package

Create an installation package on your bastion host.

1. On your bastion host, make sure that you installed stanctl as described in the Installing stanctl command-line tool section.

2. Create the air-gapped package. By default, the package is created in the current directory. To specify another location, use the --output-dir <full-path-to-directory> flag with the command. For the disk space requirement of the directory, see Storage requirements.

   • If you did not mirror any repositories for the installation, run the following command:

     stanctl air-gapped package
     

   • If you mirrored Instana repositories, use the following flags with the stanctl air-gapped package command as applicable:

     • If you mirrored the Docker registry, use the following flag:

       --registry-use-in-air-gapped
       

     • If you mirrored the Helm repository, use the following flag:

       --helm-repo-use-in-air-gapped
       

     • If you mirrored cluster artifacts, use the following flags:

       --cluster-use-in-air-gapped
       

     The following command is an example that uses all the flags:

     stanctl air-gapped package --registry-use-in-air-gapped --helm-repo-use-in-air-gapped --cluster-use-in-air-gapped
     

3. Enter the download key and sales key at the prompt. For more information about the prompts, see the Before you begin section.

   ? Enter the download key or an official agent key: **********************
   ? Enter the sales key: **********************
   

   If the keys that you entered are valid, the installer starts downloading the artifacts and creates the air-gapped package. You might see the following message:

⠇ Packaging stanctl artifacts  [1s] ✓
⠇ Packaging BuildMeta artifacts  [1s] ✓
⠇ Packaging Cluster artifacts  [1s] ✓
⠦ Packaging Geodb artifacts  [0s] ✓
⠸ Packaging Helm artifacts  [12s] ✓
⠙ Packaging License artifacts  [0s] ✓
⠴ Packaging Registry artifacts  [2m00s]

Depending on network conditions, it might take several minutes for the air-gapped package to be created.

When you see the following message, your air-gapped package is ready.

------------------------------------------
Air-gapped package successfully exported!

File: instana-airgapped.tar.gz
------------------------------------------

Transferring the air-gapped installation package

Transfer the air-gapped package from the bastion host to the Instana host that is in your air-gapped environment. In a multi-node cluster, transfer the air-gapped package to node0 (instana-0).

You must install the command-line tool stanctl on the Instana host that is in your air-gapped environment. In a multi-node cluster, you must install stanctl on node0 (instana-0).

You can install the tool by using the binary file that is provided in the air-gapped package.

1. Extract the air-gapped package and copy the stanctl file to the /usr/local/bin directory on your Instana host.

   tar -xzf </path/to/instana-airgapped.tar.gz> -C /usr/local/bin --strip-components 1 airgapped/stanctl
   

2. Import the air-gapped package.

   • If you did not mirror any repositories for the installation, run the following command:

     stanctl air-gapped import --file </path/to/instana-airgapped.tar.gz>
     

   • If you mirrored Instana repositories, use the following flags with the stanctl air-gapped import command as applicable:

     • If you mirrored the Docker registry, use the following flag:

       --registry-use-in-air-gapped
       

     • If you mirrored the Helm repository, use the following flag:

       --helm-repo-use-in-air-gapped
       

     • If you mirrored the cluster artifacts, use the following flags:

       --cluster-use-in-air-gapped
       

     The following command is an example that uses all the flags:

     stanctl air-gapped import --file </path/to/instana-airgapped.tar.gz> --registry-use-in-air-gapped --helm-repo-use-in-air-gapped --cluster-use-in-air-gapped
     

Installing the Standard Edition (air-gapped)

Install a cluster, the Instana backend, and all required data stores in an air-gapped environment. Follow the instructions in Installing the Standard Edition in an online environment.

• To install a single-node cluster, run the following command. At the prompt, enter the parameter values.

  • If you are using the Instana repository for installation, run the following command:

    stanctl up --air-gapped
    

  • If you are using a mirrored repository for installation, use the following commands:
    • For using your Docker registry, run the following command:

      stanctl up --air-gapped --registry-url <url> --registry-user <username> --registry-password <password> --registry-use-in-air-gapped
      

    • For using your Helm repository, run the following command:

      stanctl up --air-gapped --helm-repo-url <url> --helm-repo-user <username> --helm-repo-password <password> --helm-repo-use-in-air-gapped
      

    • For using your cluster artifacts, run the following command:

      stanctl up --air-gapped --cluster-url <url> --cluster-user <username> --cluster-password <password> --cluster-use-in-air-gapped
      

    • For using Docker registry, Helm repository, and cluster artifacts, run the following command:

      stanctl up --air-gapped --registry-url <url> --registry-user <username> --registry-password <password> --registry-use-in-air-gapped --helm-repo-url <url> --helm-repo-user <username> --helm-repo-password <password> --helm-repo-use-in-air-gapped --cluster-url <url> --cluster-user <username> --cluster-password <password> --cluster-use-in-air-gapped
      

• To install a multi-node cluster, run the following command on node0 (instana-0) as the user that you configured for SSH access. At the prompt, enter the parameter values.

  • If you are using the Instana repository for installation, run the following command:

    stanctl up --air-gapped --multi-node-enable
    

  • If you are using a mirrored repository for installation, use the following commands:
    • For using your Docker registry, run the following command:

      stanctl up --air-gapped --multi-node-enable --registry-url <url> --registry-user <username> --registry-password <password> --registry-use-in-air-gapped
      

    • For using your Helm repository, run the following command:

      stanctl up --air-gapped --multi-node-enable --helm-repo-url <url> --helm-repo-user <username> --helm-repo-password <password> --helm-repo-use-in-air-gapped
      

    • For using your Cluster artifacts, run the following command:

      stanctl up --air-gapped --multi-node-enable --cluster-url <url> --cluster-user <username> --cluster-password <password> --cluster-use-in-air-gapped
      

    • For using Docker registry, Helm repositories, and Cluster artifacts, run the following command:

      stanctl up --air-gapped --multi-node-enable --registry-url <url> --registry-user <username> --registry-password <password> --registry-use-in-air-gapped --helm-repo-url <url> --helm-repo-user <username> --helm-repo-password <password> --helm-repo-use-in-air-gapped --cluster-url <url> --cluster-user <username> --cluster-password <password> --cluster-use-in-air-gapped