Provisioning an eval org from the command line

You're viewing Apigee X documentation.
View Apigee Edge documentation.

This section describes how to install and configure an eval org from the command line.

Prerequisites

These instructions assume you have:

Set up a Google Cloud billing account.
Created or have management access to a Google Cloud project.

These prerequisites are described in the Introduction to provisioning > Prerequisites.

Step 1: Define environment variables

To define environment variables on the command line:

Log in to Cloud by using the following command:
```
gcloud auth login
```
The command launches a browser window and prompts you to choose an account (if you have more than one). Cloud then prompts you to allow access. You only need to do this once: You will not need to run this command, choose an account, or allow access in the future.
Initialize the Cloud SDK, as described in Initializing Cloud SDK; for example:
```
gcloud init
```
During SDK initialization, enter or select the ID of the project you created in Prerequisites. Set this project as the default. You will not need to run this command in the future unless you want to change the defaults.

You may be asked to choose a configuration to use. If you are provisioning a new Apigee installation (the assumption in these steps), choose [2] Create a new configuration.

When you run gcloud init you will be asked for:
- A configuration name. This must start with a lowercase letter and can contain a combination of lowercase letters, numbers, and dashes. You will need to refer to this name if you want to change the defaults for this Cloud configuration in the future.
- The user setting up this configuration. Typically this will be you, but it can be another user or a Cloud service account that has permissions to manage Cloud configurations.
- The Cloud project ID in which you will run Apigee. This is the project you created in Prerequisites.
- The default Compute Region and Zone and zone for your project. You can skip this step.

Define the following environment variables for the current project:

AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
PROJECT_ID="YOUR_PROJECT_ID"
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
RUNTIME_LOCATION="YOUR_RUNTIME_LOCATION"
ANALYTICS_REGION="YOUR_ANALYTICS_REGION"

Where:

AUTH defines the Authentication header with a bearer token. You will use this header to make Apigee API calls.
PROJECT_ID is the Cloud project ID that you created as part of the Prerequisites. If you're not sure what your project ID is, use Cloud Console or the gcloud projects list command to find it.
PROJECT_NUMBER is the Cloud project number that you created as part of the Prerequisites. This example issues a gcloud command to get the project number for you. Alternatively, you can use the gcloud projects list command to find it.
RUNTIME_LOCATION is the physical location where your Apigee instance will be located. Valid values are any Compute Engine region. For the list of valid region names, see Available regions and zones.

ANALYTICS_REGION is the physical location at which you store your analytics data.

Where ANALYTICS_REGION is one of the following:

`asia-northeast1`	`asia-south1`	`australia-southeast1`
`us-central1`	`us-east1`	`us-west1`
`europe-west1`	`europe-west2`	`europe-west3`

Choose a region that is geographically close or one that satisfies your organization's storage requirements.

The value of ANALYTICS_REGION does not have to be the same as RUNTIME_LOCATION. However, there may be a performance benefit if they are the same.

(Optional) Check your work by echoing the values you just set.

echo $AUTH
echo $PROJECT_ID
echo $PROJECT_NUMBER
echo $RUNTIME_LOCATION
echo $ANALYTICS_REGION

The responses to your echo commands should look something like the following:

Authorization: Bearer ya29.a123456678940B63hPSAMPLEsampleKKYVsample0f3pWDWZDuH2-hENkNa
TvgZ1PD977TMvv6edBQPJezdHw040880Ol_LoD5ZDkt-i-knizia_KhA9L20sSvztL81-SAMPLE42ELPMASk2_
1CxN
my-cloud-project
1234567890
us-west1
us-west1

Step 2: Enable APIs

To enable the required APIs for your Google project:

Enable the four required APIs listed above by executing the services enable command:

gcloud services enable apigee.googleapis.com \
  servicenetworking.googleapis.com compute.googleapis.com \
  cloudkms.googleapis.com --project=$PROJECT_ID

(Optional) To check your work, use the services list command to show all the enabled APIs:
```
gcloud services list
```
The response shows all enabled services, including the APIs that you just enabled (Apigee, Service Networking, Cloud KMS, and Compute Engine). The following example shows a possible list of APIs displayed by this command:
```
...                                    ...
apigee.googleapis.com                  Apigee API
appengineflex.googleapis.com           Google App Engine Flexible Environment
...                                    ...
cloudkms.googleapis.com                Cloud Key Management Service (KMS) API
compute.googleapis.com                 Compute Engine API
...                                    ...
servicemanagement.googleapis.com       Service Management API
servicenetworking.googleapis.com       Service Networking API
...                                            ...
```
While your list of APIs might be different than those shown above, it must include the APIs you enabled in this step. If it doesn't, try executing the previous command for each API—one at a time—to enable them. Alternatively, try using the Console to enable APIs.

Step 3: Configure service networking

To configure service networking:

Note: For most eval orgs, use default for the network parameter. default is the network that Google Cloud created for you when you created your Google Cloud project. If you have a different Cloud network and want to use it, then enter its name. (Note that the network must have a /22 CIDR block of IP addresses free.)

Create a peering range using the following command:
```
gcloud compute addresses create google-svcs \
  --global \
  --prefix-length=22 \
  --description="Peering range for Google services" \
  --network=default # For evals, use 'default' for the network. \
  --purpose=VPC_PEERING \
  --project=$PROJECT_ID
```
Where:
- google-svcs is the name of the IP address range you are creating.
- --global specifies the scope of the IP addresses. You must include this in your command.
- --prefix-length specifies the size of the CIDR block (the number of IP addresses allowed in the range). The value must be 22 for an eval installation.
- --description specifies human-readable information about the service.
- --network is the name of the network resource in which the addresses should be reserved. For eval purposes, use default for this setting.
  Google creates a default network (named default) for each new project, so you can use that. However, we do not recommend using the default network for anything other than testing.
- --purpose is the type of address resource. Set the value of purpose to VPC_PEERING.
- --project is your Cloud project's ID, for which you can use the variable value that you defined previously ($PROJECT_ID).
On success, gcloud responds with the following:
```
Created [https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/global/addresses/google-svcs].
```
After you create a range of IP addresses, the addresses are associated with the project until you release them.
Connect your services to the network using the following command:
```
gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --network=default \
  --ranges=google-svcs \
  --project=$PROJECT_ID
```
Use the same network name you used previously (for example, default). This operation can take several minutes to complete.

On success, gcloud responds with the following:
```
Operation "operations/OPERATION_ID" finished successfully.
```
Where OPERATION_ID is the UUID of the LRO.

Apigee creates a connection between your network and Google's services; specifically, Apigee connects your project to the Service Networking API through VPC peering. Apigee also associates IP addresses with your project.

Step 4: Create an organization

To create a new eval org:

Create a new eval org using the gcloud apigee organizations command:

gcloud alpha apigee organizations provision \
  --runtime-location=$RUNTIME_LOCATION \
  --analytics-region=$ANALYTICS_REGION \
  --authorized-network=NETWORK_NAME \
  --project=$PROJECT_ID

Where --authorized-network is the name of your custom peering network. For example: default.

When you execute the provision command, Google starts an LRO (long-running operation) to create the eval org. This operation takes about 15 minutes to complete. During that time, gcloud displays the following:
```
Provisioning organization...
```
Note: The provision command can create only eval organizations. It cannot be used to create production organizations.

(Optional) Check the status of your LRO by using the operations list command:

gcloud alpha apigee operations list

If Google is not yet done creating the eval org, the response includes an IN_PROGRESS status:

UUID                               ORGANIZATION  STATE
...
f48a00ff-7daa-4c4a-4444-7SAMPLE7f  my-org        IN_PROGRESS

When Google finishes creating the eval org and its associated runtime instance, gcloud responds with the following:

Provisioning organization...done.

If you execute the operations list command again, you should see that all UUIDs are in the FINISHED state. For example:

UUID                                  ORGANIZATION  STATE
00bab06f-c60c-41a5-4242-7SAMPLE7f     my-org        FINISHED
429790a7-3151-4642-4343-7SAMPLE7f     my-org        FINISHED
d00a92a9-9b83-4642-4343-7SAMPLE7f     my-org        FINISHED
f48a00ff-7daa-4c4a-4444-7SAMPLE7f     my-org        FINISHED

Step 5: Do a final test

An API proxy called hello-world was created for you during provisioning. By default, proxies you create in an eval org have internal-only access. To test your newly provisioned org, follow the steps in Calling an API proxy with internal-only access.

If you want to allow external access to your API proxy, follow the external configuration steps in Configure routing.