You can create an organization, environment, and virtual host on the command line in a single command, or you can create each one separately. In addition, you can use the Edge API to perform many of these actions.
Video: Watch a short video for an overview of Apigee Organization setup and configuration.
Creating an organization, environment, and virtual host at the same time
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
Where configFile is the path to a configuration file that looks similar to the following:
# Set Edge sys admin credentials. ADMIN_EMAIL=your@email.com APIGEE_ADMINPW=admin_password # If omitted, you are prompted for it. NEW_USER="y" USER_NAME=orgAdmin@myCo.com FIRST_NAME=foo LAST_NAME=bar USER_PWD="userPword" ORG_NAME=example # lowercase only, no spaces, underscores, or periods. ENV_NAME=prod # lowercase only 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
When setting up an organization, the setup-org
script does the following:
- Creates the organization.
- Associates the organization with the "gateway" pod. You cannot change this.
- Adds the specified user as the organization admininstrator. If the user does not exist, you can create one.
- Creates one or more environments.
- Creates one or more virtual hosts for each environment.
- Associates the environment with all Message Processor(s).
- Enables analytics.
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. Both the org name and environment
name must be lower case.
Create an organization
Use the create-org
command to create an organization, as the following example
shows:
/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 configuration file contains the name of the organization and the email address of the organization
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=admin_password # If omitted, you are prompted for it. ORG_NAME=example # lowercase only, no spaces, underscores, or periods. ORG_ADMIN=orgAdmin@myCo.com
The create-org
script:
- Creates the organization.
- Associates the organization with the "gateway" pod.
- Adds the specified user as the organization admininstrator. The user must already exist; otherwise the script issues an error.
Create an organization by using API calls
You can use the following API calls to create an organization. The first call creates the organization:
curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \ -X POST http://management_server_IP:8080/v1/organizations \ -d '<Organization name="org_name" type="paid"/>'
The next call associates the organization with a pod:
curl -H "Content-Type:application/x-www-form-urlencoded" \ -u sysAdminEmail:adminPasswd -X POST \ http://management_server_IP:8080/v1/organizations/org_name/pods \ -d "region=default&pod=gateway"
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
script to create an environment in an existing organization:
/opt/apigee/apigee-service/bin/apigee-service apigee-provision add-env -f configFile
This config file contains the information necessary to create the environment and virtual host:
APIGEE_ADMINPW=admin_password # If omitted, you are prompted for it. ORG_NAME=example # lowercase only, no spaces, underscores, or periods. ENV_NAME=prod # lowercase only 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 add-env
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
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://management_server_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://management_server_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://Message_Processor_IP:8082/v1/servers/self
Where Message_Processor_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.
This config file contains:
ORG_NAME=orgName # lowercase only, no spaces, underscores, or periods. ENV_NAME=envName # lowercase only
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 following command:
curl -u sysAdminEmail:password http://management_server_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 following command:
curl -u sysAdminEmail:admin_password http://management_server_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://management_server_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>'
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.