Creating an Organization, Environment, and Virtual Host

Edge for Private Cloud v4.18.01

Creating an Organization, Environment, and Virtual Host at the same time

Video: Watch a short video for an overview of Apigee Organization setup and configuration.

Before you create an API proxy on Apigee Edge, you must create at least one organization and, within each organization, one or more environments and virtual hosts.

Typically, organizations and environments are created together. To simplify the process, use the apigee-provision utility. Invoke it from the command line on the Edge Management Server:

/opt/apigee/apigee-service/bin/apigee-service apigee-provision setup-org -f configFile

The config file contains:

# Set Edge sys admin credentials.
ADMIN_EMAIL=your@email.com
APIGEE_ADMINPW=adminPword     # If omitted, you are prompted for it.
NEW_USER="y"
USER_NAME=orgAdmin@myCo.com
FIRST_NAME=foo
LAST_NAME=bar
USER_PWD="userPwrod"
ORG_NAME=example  # lowercase only, no spaces, underscores, or periods.
ENV_NAME=prod
VHOST_PORT=9001
VHOST_NAME=default
VHOST_ALIAS="$IP1:9001"
# Optionally configure TLS/SSL for virtual host.
# VHOST_SSL=y     # Set to "y" to enable TLS/SSL on the virtual host.
# KEYSTORE_JAR=   # JAR file containing the cert and private key.
# KEYSTORE_NAME=  # Name of the keystore. 
# KEYSTORE_ALIAS= # The key alias.
# KEY_PASSWORD=   # The key password, if it has one. 
# Optionally set the base URL displayed by the Edge UI for an
# API proxy deployed to the virtual host.
# VHOST_BASEURL="http://myCo.com"
# AXGROUP=axgroup-001 # Default value is axgroup-001

The command then:

Create the organization
Note: You cannot rename an organization after you create it.
Associate the organization with a pod, by default is associates it with the "gateway" pod
Add the specified user as the org admin. If the user does not exist, you can create one.
Create one or more environments
Create one or more virtual host for each environment
Associate the environment with all Message Processor(s)
Enable analytics

For a complete silent config file, see Onboard an organization.

By default, the maximum length of the organization name and environment name is 20 characters when using the apigee-provision utility. This limit does not apply if you use the Edge API directly to create the organization or environment.

Note: Rather than using the apigee-provision utility, you can use a set of additional scripts, or the Edge API itself, to create and configure an organization. For example, use thee scripts to add an organization and associate it with multiple pods. The following sections describe those scripts and APIs in more detail.

Create an Organization

Use the create-org command to create an organization:

/opt/apigee/apigee-service/bin/apigee-service apigee-provision create-org -f configFile

This script creates the organization, but does not add or configure the environments and virtual hosts required by the organization to handle API calls.

The config file contains the name of the org and the email address of the org admin. The characters you can use in the name attribute are restricted to: a-z0-9\-$%. Do not use spaces, periods or upper-case letters in the name:

APIGEE_ADMINPW=adminPword    # If omitted, you are prompted for it.
ORG_NAME=example  # lowercase only, no spaces, underscores, or periods.
ORG_ADMIN=orgAdmin@myCo.com

The command then:

Creates the organization
Associates the organization with a pod, by default is associates it with the "gateway" pod
Adds the specified user as the org admin. The user must already exist; otherwise the script issues an error.

<Error>
  <Code>organizations.OrganizationAlreadyExists</Code>
  <Message>Organization : test already exists</Message>
  <Contexts/>
</Error>

Create an organization by using API calls

Alternatively, you can use the following API calls to create an org. The first call creates the org:

curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://ms-ip:8080/v1/organizations \
  -d '<Organization name="org-name" type="paid"/>'

The next call associates the org with a pod:

curl -H "Content-Type:application/x-www-form-urlencoded" \
  -u sysAdminEmail:adminPasswd -X POST \
  http://ms-ip:8080/v1/organizations/org-name/pods \
  -d "region=default&pod=gateway"

You can make this call multiple times to associate the organization with multiple pods.

The final call adds an existing user as the org admin for the org:

curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://ms-ip:8080/v1/organizations/org-name/users/user-email/userroles/ \
  -d '<Roles><Role name="orgadmin"/></Roles>'

If the user does not exist, you can use the following call to create the user as described in Adding a user.

Create an Environment

Use the add-env command to create an environment in an existing organization:

/opt/apigee/apigee-service/bin/apigee-service apigee-provision add-env -f configFile

This config file contain the information necessary to create the environment and virtual host:

APIGEE_ADMINPW=adminPword    # If omitted, you are prompted for it.
ORG_NAME=example  # lowercase only, no spaces, underscores, or periods.
ENV_NAME=prod
VHOST_PORT=9001
VHOST_NAME=default
VHOST_ALIAS="$IP1:9001"
# Optionally configure TLS/SSL for virtual host.
# VHOST_SSL=y     # Set to "y" to enable TLS/SSL on the virtual host.
# KEYSTORE_JAR=   # JAR file containing the cert and private key.
# KEYSTORE_NAME=  # Name of the keystore. 
# KEYSTORE_ALIAS= # The key alias.
# KEY_PASSWORD=   # The key password, if it has one. 
# Optionally set the base URL displayed by the Edge UI for an
# API proxy deployed to the virtual host.
# VHOST_BASEURL="http://myCo.com"
# AXGROUP=axgroup-001 # Default value is axgroup-001

The command:

Creates the environment
Creates a single virtual host for the environment
Associates the environment with all Message Processor(s) in the pod associated with the organization containing the environment.
Enables analytics
Note: If you enable analytics for one environment in an organization, you must enable analytics for all environments in the organization.

Create an environment by using API calls

Alternatively, you can use the following API calls to create an environment. The first call creates the environment:

curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://ms-ip:8080/v1/organizations/org-name/environments \
  -d '<Environment name="env-name"/>'

The next call associates the environment with a Message Processor. Make this call for each Message Processor that you want to associate with the environment:

curl -H "Content-Type:application/x-www-form-urlencoded" \
  -u sysAdminEmail:adminPasswd -X POST \
  http://ms-ip:8080/v1/organizations/org-name/environments/env-name/servers \
  -d "action=add&uuid=uuid"

Where uuid is the UUID of Message Processor. You can obtain the UUID by using the command:

curl http://mp-ip:8082/v1/servers/self

Where mp-ip is the IP address of the Message Processor.

The next API call enables Analytics for a given environment. It validates the existence of Qpid and Postgres Servers in the PODs of all datacenters. Then it starts the Analytics onboarding for the given organization and environment.

/opt/apigee/apigee-service/bin/apigee-service apigee-provision enable-ax -f configFile

This config file contains:

ORG_NAME=orgName  # lowercase only, no spaces, underscores, or periods.
ENV_NAME=envName

curl -H "Content-Type:application/json" -u sysAdminEmail:adminPasswd
  -X POST http://ms-ip:8080/v1/organizations/org-name/environments/env-name/analytics/admin -d "@sample.json"

Where sample.json contains the following:

{
  "properties" : {
    "samplingAlgo" : "reservoir_sampler",
    "samplingTables" : "10=ten;1=one;",
    "aggregationinterval" : "300000",
    "samplingInterval" : "300000",
    "useSampling" : "100",
    "samplingThreshold" : "100000"
  },
  "servers" : {
    "postgres-server" : [ "1acff3a5-8a6a-4097-8d26-d0886853239c", "f93367f7-edc8-4d55-92c1-2fba61ccc4ab" ],  
    "qpid-server" : [ "d3c5acf0-f88a-478e-948d-6f3094f12e3b", "74f67bf2-86b2-44b7-a3d9-41ff117475dd"] 
  }
}

The postgres-servers property contains a comma-separated list of the Postgres UUIDs, and the qpid-server property contains the Qpid UUIDs. If you need to obtain these UUIDs, use the following commands.

For Qpid, run the command:

curl -u sysAdminEmail:passwd http://ms-ip/v1/servers?pod=central

The output of this command is a JSON object. For each Qpid server, you will see output in the form:

"type" : [ "qpid-server" ],
"uUID" : "d3c5acf0-f88a-478e-948d-6f3094f12e3b"

For Postgres, run the command:

curl -u sysAdminEmail:passwd http://ms-ip/v1/servers?pod=analytics

For each Postgres server, you will see output in the form:

"type" : [ "postgres-server" ],
"uUID" : "d3c5acf0-f88a-478e-948d-6f3094f12e3b"

Create a Virtual Host

You can create a virtual host in an existing environment in an organization. Often an environment supports multiple virtual hosts. For example, one virtual host might support the HTTP protocol, while another virtual host in the same environment supports the encrypted HTTPS protocol.

Use the following API call to create additional virtual hosts, or to create a virtual host for an environment with no virtual host:

curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://ms-ip:8080/v1/organizations/org-name/environments/env-name/virtualhosts \
  -d '<VirtualHost name="default"> \
    <HostAliases> \
      <HostAlias>myorg-test.apigee.net</HostAlias> \ 
    </HostAliases> \
    <Interfaces/> \
    <Port>443</Port> \
  </VirtualHost>'

Note: The characters you can use in the name attribute are restricted to: a-zA-Z0-9._\-$%.

For a complete description of creating a virtual host, including creating a secure virtual host that uses TLS/SSL over HTTPS, see Configuring TLS access to an API for the Private Cloud.