> [!CAUTION]
> You are currently viewing version 1.1 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.1 (unsupported)</button>

- Supported versions:
- [v1.17 (latest)](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/install-download-install-anthos.html)
- [v1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/install-download-install-anthos.html)
- [v1.15](https://docs.cloud.google.com/apigee/docs/hybrid/v1.15/install-download-install-anthos.html)
- [v1.14](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/install-download-install-anthos.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-anthos.html)
- [v1.12](https://docs.cloud.google.com/apigee/docs/hybrid/v1.12/install-download-install-anthos.html)
- [v1.11](https://docs.cloud.google.com/apigee/docs/hybrid/v1.11/install-download-install-anthos.html)
- [v1.10](https://docs.cloud.google.com/apigee/docs/hybrid/v1.10/install-download-install-anthos.html)
- [v1.9](https://docs.cloud.google.com/apigee/docs/hybrid/v1.9/install-download-install-anthos.html)
- [v1.8](https://docs.cloud.google.com/apigee/docs/hybrid/v1.8/install-download-install-anthos.html)
- [v1.7](https://docs.cloud.google.com/apigee/docs/hybrid/v1.7/install-download-install-anthos.html)
- [v1.6](https://docs.cloud.google.com/apigee/docs/hybrid/v1.6/install-download-install-anthos.html)
- [v1.5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.5/install-download-install-anthos.html)
- [v1.4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/install-download-install-anthos.html)
- [v1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/install-download-install-anthos.md.txt)
- [v1.2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/install-download-install-anthos.md.txt)
- [v1.1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-download-install-anthos.md.txt)

This step explains how to download and install [apigeectl](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/cli-reference)
on your Anthos GKE deployed on-prem admin machine. Steps include
setting up the installation directories, creating GCP service accounts that are required for
hybrid components to communicate, and creating TLS credentials
that are required for Apigee hybrid to operate.

## Download and install apigeectl

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

**To get `apigeectl`:**

1. Download the release package to your GKE on-prem admin machine:

   **Mac 64 bit:**

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

   **Linux 64 bit**

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

   **Mac 32 bit:**

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

   **Linux 32 bit**

   ```
   curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.1.1/apigeectl_linux_32.tar.gz
   ```
2. Create a directory on your system to serve as the **base directory** for the Apigee hybrid installation.
3. Extract the downloaded gzip file contents into the base directory you just created. For example:

   ```
   tar xvzf filename.tar.gz -C path-to-base-directory
   ```
4. `cd` to the base directory.
5. 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`:

       mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl

6. `cd`into the directory. For example:
`cd ./apigeectl`
7. This directory will be the `apigeectl` home directory. It is where the `apigeectl` executable command is located.
8. Create an environment variable to hold this home directory path: <br />

   ```
   export APIGEECTL_HOME=$PWD
   ```

   <br />

9. Verify that the variable holds the correct path:

   ```
   echo $APIGEECTL_HOME
   ```

## Set up the project directory structure


The directory structure described below 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 will 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.1/upgrade.md.txt).

> [!NOTE]
> **NOTE:**For the purpose of this quickstart, subsequent installation steps assume that you created the project structure as described below. If you follow this suggested structure, you will be able to 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).
2. Create a new folder called `hybrid-files`. You can give the directory any name you wish, but in the docs, the name `hybrid-files` will be 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 this:

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

4. `cd` into the `hybrid-files`folder:

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

       mkdir overrides
       mkdir service-accounts
       mkdir certs

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

       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 this command and make sure the link paths point to the correct locations:

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

## Create service accounts


Apigee hybrid uses GCP [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.

### *Click to learn more*

The following table describes the service accounts that are required by hybrid components
to perform authorized communication. See
also [About service accounts](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/sa-about.md.txt).

| Component^\*^ | Role | Required for basic install? | Description |
|---|---|---|---|
| `apigee-cassandra` | Storage Object Admin | Yes | Allows Cassandra backups to Google Cloud Storage, as described in [Backup and recovery](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/backup-recovery.md.txt). |
| `apigee-logger` | Logs Writer | No | Allows logging data collection, as described in [Logging](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/logging.md.txt). Only required for non-GKE cluster installations. |
| `apigee-mart` | *No role* | Yes | Allows MART service authentication. This service account should not have a role associated with it; as a result, when you create this service account, do not assign a role to it. |
| `apigee-metrics` | Monitoring Metric Writer | No | Allows metrics data collection, as described in [Metrics collection](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/metrics-collection.md.txt) |
| `apigee-org-admin` | Apigee Organization Admin | Yes | Lets you call the [getSyncAuthorization API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations/getSyncAuthorization.md.txt) and [setSyncAuthorization API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations/setSyncAuthorization.md.txt). You cannot create this service account with the `create-service-account` tool. |
| `apigee-synchronizer` | Apigee Synchronizer Manager | Yes | Allows the synchronizer to download proxy bundles and environment configuration data. Also enables operation of the trace feature. |
| `apigee-udca` | Apigee Analytics Agent | Yes | Allows the transfer of trace, analytics and deployment status data to the management plane. |
| ^\*^ This name is used in the downloaded service account key's filename. ||||


Create the keys:

1. Be sure that you are in the `base_directory/hybrid-files` directory:
2. Execute the following command from inside `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 this prompt, enter `y`:

   ```
   [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, select `y` 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:

       ./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

4. Verify that the service account keys were created. You are responsible for storing these private keys securely. The keys filenames are prefixed with the name of your GCP project. For example:

   ```
   ls ./service-accounts
   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
   ```

> [!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.1/cli-reference) 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.1/sa-validation).

## Create TLS certificates


You are required to provide TLS certificates for the MART and runtime ingress gateways in your
Apigee hybrid configuration. The credentials used for the MART gateway *must* be
authorized by a certificate authority (CA).
For the purpose of this quickstart (a non-production trial installation),
the runtime gateway can accept self-signed credentials.


In this step, you will create the TLS credential files and add them to
the `base_directory/hybrid-files/certs` directory.
In [Step 3: Configure the cluster](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-copy-overrides.md.txt), you will add the file
paths to the cluster configuration file.

### Create TLS credentials for the runtime gateway


The runtime ingress gateway (the gateway that handles API proxy traffic) requires
a TLS certificate/key pair. For this quickstart installation, you can use self-signed
credentials. In the following steps, [openssl](https://www.openssl.org/) is used
to generate the credentials.

1. Be sure that you are in the `base_directory/hybrid-files` directory.
2. Execute the following command from inside `hybrid-files` directory:

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


   This command creates a self-signed certificate/key pair that you can use for the
   quickstart installation. The CN `mydomain.net` can be any value you wish for
   the self-signed credentials.
3. Check to make sure the files are in the `./certs` directory:

       ls ./certs
         keystore.pem
         keystore.key


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

### Create TLS credentials for the MART gateway


As noted in [Before you begin](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-before-begin.md.txt), you *must* use
an authorized TLS certificate/key pair for the MART gateway configuration. If you have
not done so, obtain or create these credentials now.

1. Obtain or create an TLS certificate/key pair that is authorized by a certificate authority. An example is provided showing how to obtain these credentials using the Let's Encrypt CA. Note that the certificate's common name (CN) must be a valid DNS name. For the example steps, see [Obtain TLS credentials: An example](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/lets-encrypt.md.txt).
2. Copy the credentials into the `base_directory/hybrid-files/certs` directory.
3. When you are finished, you should have two pairs of credential files in the `./certs` directory. For example:

       ls ./certs
         fullchain.pem
         privkey.key
         keystore.pem
         keystore.key


   Where `fullchain.pem` is the authorized TLS certificate file and `privkey.key`
   is the authorized key file.

## Summary


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 will be used by Kubernetes
to deploy the hybrid runtime components to the cluster.
[1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-create-cluster-anthos.md.txt) [2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-download-install-anthos.md.txt) [(NEXT) Step 3: Configure the cluster](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-copy-overrides-anthos.md.txt) [4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/install-apply-hybrid-anthos.md.txt)

<br />