Step 2: Install and set up

This step explains how to download and install apigeectl, set up the installation directories, and create GCP service accounts, and 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 for your operating system:

    Mac 64 bit:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt)/apigeectl_mac_64.tar.gz

    Linux 64 bit

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt)/apigeectl_linux_64.tar.gz

    Mac 32 bit:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt)/apigeectl_mac_32.tar.gz

    Linux 32 bit

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt)/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. cdinto the directory. For example:
  7. cd ./apigeectl

    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:

    export APIGEECTL_HOME=$PWD

  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.

  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-filesfolder:
    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 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.

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 willwitman-istio.
     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

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

Next Step

1 2 NEXT: (3) Configure the cluster 4