> [!CAUTION]
> You are currently viewing version 1.3 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions).

<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.3 (unsupported)</button>

- Supported versions:
- [v1.17 (latest)](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/install-download-install-eks.html)
- [v1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/install-download-install-eks.html)
- [v1.15](https://docs.cloud.google.com/apigee/docs/hybrid/v1.15/install-download-install-eks.html)
- [v1.14](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/install-download-install-eks.html)
- [List of supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions)
- Unsupported versions:
- [v1.13](https://docs.cloud.google.com/apigee/docs/hybrid/v1.13/install-download-install-eks.html)
- [v1.12](https://docs.cloud.google.com/apigee/docs/hybrid/v1.12/install-download-install-eks.html)
- [v1.11](https://docs.cloud.google.com/apigee/docs/hybrid/v1.11/install-download-install-eks.html)
- [v1.10](https://docs.cloud.google.com/apigee/docs/hybrid/v1.10/install-download-install-eks.html)
- [v1.9](https://docs.cloud.google.com/apigee/docs/hybrid/v1.9/install-download-install-eks.html)
- [v1.8](https://docs.cloud.google.com/apigee/docs/hybrid/v1.8/install-download-install-eks.html)
- [v1.7](https://docs.cloud.google.com/apigee/docs/hybrid/v1.7/install-download-install-eks.html)
- [v1.6](https://docs.cloud.google.com/apigee/docs/hybrid/v1.6/install-download-install-eks.html)
- [v1.5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.5/install-download-install-eks.html)
- [v1.4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/install-download-install-eks.html)
- [v1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-download-install-eks.md.txt)
- [v1.2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/install-download-install-eks.html)
- [v1.1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-download-install-eks.html)

This step explains how to download and install [apigeectl](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/cli-reference.md.txt).
Steps include
setting up the installation directories, creating Google Cloud service accounts that are required
for hybrid components to communicate, and creating TLS credentials that are required for
Apigee hybrid to operate.


For more information on using `apigeectl` and `kubectl` to manage clusters,
see [Connecting
to your cluster with kubectl]()

## Download and install `apigeectl`

`apigeectl` is the command-line interface
(CLI) for installing and managing Apigee hybrid in a Kubernetes cluster.

The following steps describe how to get `apigeectl`:

1. Store the latest version number in a variable using the following command:

   ```
   export VERSION=$(curl -s \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
   ```
2. Check that the variable was populated with a version number using the following command. If you want to use a different version, you can save that in an environment variable instead.

   ```
   echo $VERSION
   ```
3. Download the release package for your operating system using the following command:

   **Mac 64 bit:**

   ```
   curl -LO \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz
   ```

   **Linux 64 bit:**

   ```
   curl -LO \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz
   ```

   **Mac 32 bit:**

   ```
   curl -LO \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_mac_32.tar.gz
   ```

   **Linux 32 bit:**

   ```
   curl -LO \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
   ```
4. Create a directory on your system to serve as the **base directory** for the Apigee hybrid installation.
5. Extract the downloaded gzip file contents into the base directory you just created using the
   following command:

   ```
   tar xvzf filename.tar.gz -C path-to-base-directory
   ```
6. Change directory to the base directory using the `cd` command.
7. The tar contents are, by default, expanded into a directory with the version and platform in
   its name. For example: `./apigeectl_1.0.0-f7b96a8_linux_64`. Rename that directory
   to `apigeectl` using the following command:

   ```
   mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
   ```
8. Change to the directory using the following command:

   ```
   cd ./apigeectl
   ```


   This directory is the `apigeectl` home directory. It is where the `apigeectl`
   executable command is located.
9. Create an environment variable to hold this home directory path using the following command:

   ```
   export APIGEECTL_HOME=$PWD
   ```
10. Verify that the variable holds the correct path using the following command:

    ```
    echo $APIGEECTL_HOME
    ```

## Set up the project directory structure


The following directory structure is a suggested approach. It separates Apigee hybrid
release software from configuration files that you must create. Through the use of the
`$APIGEECTL_HOME` variable and symbolic links that you create, you can easily
switch to a new software version if you choose to. See also [Upgrading Apigee hybrid](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/upgrade.md.txt).

> [!NOTE]
> **Note:** For the purpose of this quickstart, subsequent installation steps assume that you created the project structure as described in this section. If you follow this suggested structure, you can copy and paste most installation commands directly into your terminal.

1. Be sure you are in the base directory (the directory where the `apigeectl` directory is located) by using the following command:

   ```
   cd $APIGEECTL_HOME/..
   ```
2. Create a new folder called `hybrid-files` using the following command. You can give the directory any name you wish, but in the docs, the name `hybrid-files` is used consistently. Later, you will store configuration files, service account keys, and TLS certificates in this folder. This folder lets you keep your config files separate from the `apigeectl` software installation.

   ```
   mkdir hybrid-files
   ```
3. The current directory structure now looks like the following:

       pwd && ls
       /hybrid-base-directory
         apigeectl
         hybrid-files

4. Change directory into the `hybrid-files`folder using the following command:

   ```
   cd hybrid-files
   ```
5. Inside the `hybrid-files` directory, create the following subdirectories to organize files that you will create later:

       mkdir overrides
       mkdir service-accounts
       mkdir certs

6. Inside the `hybrid-files` directory, create the following symbolic links to `$APIGEECTL_HOME`. These links allow you to run the `apigeectl` command from inside the `hybrid-files` directory as the following example shows:

   > [!NOTE]
   >
   > **Note:** If this is not the first time you have used this process, the following symbolic links
   > may already exist. Check to see if the links already exist using the
   > following command. If the directories exist, skip this step.
   >
   > ```
   > ls -l | grep ^l
   > ```

       ln -s `$APIGEECTL_HOME`/tools tools
       ln -s `$APIGEECTL_HOME`/config config
       ln -s `$APIGEECTL_HOME`/templates templates
       ln -s `$APIGEECTL_HOME`/plugins plugins

7. To check that the symlinks were created correctly, execute the following command and make sure the link paths point to the correct locations:

   ```
   ls -l | grep ^l
   ```

## Create service accounts


Apigee hybrid uses Google Cloud [service accounts](https://cloud.google.com/iam/docs/service-accounts) to allow hybrid components to communicate by making authorized
API calls. In this step, you use an Apigee hybrid command-line tool to create a set of services
accounts. The tool also downloads the service account private keys for you. You must then add
these keys to your Apigee hybrid cluster configuration file.

> [!NOTE]
> **Note:** To learn more about service accounts, see the following:
>
> - [About service accounts](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/sa-about.md.txt)
> - [Service accounts and roles used by hybrid components](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/sa-about.md.txt#recommended-sas)


Apigee provides a tool, `create-service-account`, that creates the service account,
assigns the roles to the service account, and creates and downloads the key files for the service
account in a single command. To learn about the related Google Cloud concepts, see
[Creating
and managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) and
[Creating
and managing service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).

1. Be sure that you are in the `base_directory/hybrid-files` directory you configured in [Set up the project directory structure](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-download-install-eks.md.txt#setup-directory).
2. Execute the following command from inside the `hybrid-files` directory. This command creates a service account for the `apigee-metrics` component and places the downloaded key in the `./service-accounts` directory.

   ```
   ./tools/create-service-account apigee-metrics ./service-accounts
   ```


   When you see the following prompt, enter <kbd>y</kbd>:

   ```
   [INFO]: gcloud configured project ID is project_id.
    Press: y to proceed with creating service account in project: project_id
    Press: n to abort.
   ```


   If this is the first time an SA with the exact name assigned by the tool was created, then
   the tool just creates it, and you do not have to do anything further.


   If, however, you see the following message and prompt, enter <kbd>y</kbd> to generate
   new keys:

   ```
   [INFO]: Service account apigee-metrics@project_id.iam.gserviceaccount.com already exists.
   ...
    [INFO]: The service account might have keys associated with it. It is recommended to use existing keys.
    Press: y to generate new keys.(this does not de-activate existing keys)
    Press: n to skip generating new keys.
   ```
3. Now, create the rest of the service accounts using the following commands. The `create-service-account` command is interactive and requires a response for each account.

   ```
   ./tools/create-service-account apigee-synchronizer ./service-accounts
   ```

   ```
   ./tools/create-service-account apigee-udca ./service-accounts
   ```

   ```
   ./tools/create-service-account apigee-mart ./service-accounts
   ```

   ```
   ./tools/create-service-account apigee-cassandra ./service-accounts
   ```

   ```
   ./tools/create-service-account apigee-logger ./service-accounts
   ```

   ```
   ./tools/create-service-account apigee-watcher ./service-accounts
   ```

   > [!NOTE]
   > **Note:** The Cloud Pub/Sub API must be enabled in the Google Cloud project that owns the service account for Synchronizer. See [Enable APIs](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/precog-enableapi.md.txt).

4. Verify that the service account keys were created using the following command. You are responsible for storing these private keys securely. The key filenames are prefixed with the name of your Google Cloud project.

   ```
   ls ./service-accounts
   ```


   The result should look something like the following:

   ```
   gcp-project-id-apigee-cassandra.json
   gcp-project-id-apigee-logger.json
   gcp-project-id-apigee-mart.json
   gcp-project-id-apigee-metrics.json
   gcp-project-id-apigee-synchronizer.json
   gcp-project-id-apigee-udca.json
   gcp-project-id-apigee-watcher.json
   ```

> [!NOTE]
> **Tip:** Apigee hybrid includes a validator that checks your service accounts' key files and permissions when [apigeectl](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/cli-reference.md.txt) applies the Apigee hybrid runtime components to your cluster. This validation is enabled by default. For more information, see [Service account
> validation](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/sa-validation).

5. Assign the Apigee Organization Admin role to the `apigee-org-admin` service accounts:
6. Verify that the email address for the `apigee-org-admin` service account follows the pattern `service_account@PROJECT_ID.iam.gserviceaccount.com` as the following example shows:

   ```
   gcloud iam service-accounts list --filter "apigee-org-admin"
   ```
7. Assign the role with the following command:

   ```
   gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:apigee-org-admin@$PROJECT_ID.iam.gserviceaccount.com --role roles/apigee.admin
   ```


   Where **PROJECT_ID** is your Google Cloud project. If your service account email addresses
   differ from this pattern, replace them accordingly.


   The output should include a list of all the service accounts and their roles, including the
   following:

       - members:
         - serviceAccount:apigee-org-admin@hybrid-example-2.iam.gserviceaccount.com
         role: roles/apigee.admin

## Create TLS certificates


You are required to provide TLS certificates for the runtime ingress gateway in your
Apigee hybrid configuration. For the purpose of this quickstart (a non-production trial installation),
the runtime gateway can accept self-signed credentials. In the following steps,
[openssl](https://www.openssl.org/) is used to generate the self-signed credentials.

> [!NOTE]
> **Note:** In a production environment, you will need to use signed certificates. You can either use either a certificate and key pair or a Kubernetes secret. For an example on how to obtain a TLS certificate from the *Lets Encrypt* certificate authority (CA), see [Obtain TLS credentials: An example](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/lets-encrypt.md.txt).


In this step, you will create the TLS credential files and add them to
the `base_directory/hybrid-files/certs` directory.
In

[Step 4: Configure the cluster](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-copy-overrides-eks.md.txt),

you will add the file paths to the cluster configuration file.

1. Be sure that you are in the `base_directory/hybrid-files` directory you configured in [Set up the project directory structure](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-download-install-eks.md.txt#setup-directory).
2. Make sure your domain name is saved to the **`DOMAIN`** environment variable using the following command:

   ```
   echo $DOMAIN
   ```
3. Execute the following command from inside the `hybrid-files` directory:

   ```
   openssl req  -nodes -new -x509 -keyout ./certs/keystore.key -out \
       ./certs/keystore.pem -subj '/CN='$DOMAIN'' -days 3650
   ```


   Where **`DOMAIN`** is the domain you reserved for your hybrid installation in
   [Quickstart (hybrid) Step 5: Configure your DNS](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/precog-add-dns.md.txt).


   This command creates a self-signed certificate/key pair that you can use for the quickstart
   installation.
4. Check to make sure the files are in the `./certs` directory using the following command:

       ls ./certs
         keystore.pem
         keystore.key


   Where `keystore.pem` is the self-signed TLS certificate file and `keystore.key`
   is the key file.


You now have a home base from which you can configure, deploy, and manage Apigee hybrid
in your Kubernetes cluster. Next, you will create a file that is used by Kubernetes
to deploy the hybrid runtime components to the cluster.
[1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-create-cluster-eks.md.txt) [2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-download-cert-manager-istio-eks.md.txt) [3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-download-install-eks.md.txt) [(NEXT) Step 4: Configure the cluster](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-copy-overrides-eks.md.txt) [5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-apply-hybrid-eks.md.txt)

<br />