C Exalogic vDC Management Using IaaS CLI: Basic Tasks

This appendix describes how to perform basic tasks related to Exalogic Virtual Data Center (vDC) management using the Infrastructure As A Service (IaaS) command-line interface. It discusses how to create and use vDC resources. For information on deleting such resources, see Appendix D, "Deleting Exalogic vDC Resources Using the IaaS CLI: Example Procedures."

Note:

This appendix describes some of the important tasks only. For information about all the IaaS commands, see the Oracle Enterprise Manager Ops Center API and CLI Reference Guide.

This appendix contains the following topics:

C.1 Overview

IaaS CLI offers the same functions and features as Cloud Management API or Java Client API. In a typical scenario, the CLI is installed on a machine outside of the Exalogic machine. This remote machine must have network access to Exalogic Control.

In this guide, the Cloud Admin user's tasks use the Browser User Interface (BUI) method, and Cloud User tasks use CLI as well as BUI.

C.2 Prerequisites

Complete the following prerequisites for using the IaaS CLI on a remote machine:

  • Install the IaaS CLI client package on the remote machine, as described in Appendix B, "Installing the Cloud Management API and CLI."

  • Ensure that the remote machine, on which the CLI client is installed, can access the Exalogic Control network.

  • Ensure that the IaaS user is added to Exalogic Control locally or via LDAP.

C.3 Setting Up and Administering Exalogic vDC

As the Cloud Admin user, use the Browser User Interface (BUI) of Exalogic Control to set up and administer the vDC on Exalogic, as described in Section 9.1, "Administering the Exalogic vDC and Setting Up the Infrastructure."

C.4 Creating and Managing vDC Resources

This section contains the following topics:

C.4.1 Overview of CLI Commands

Cloud Management CLI commands one of the following prefixes:

  • akm

    Commands used for tasks related to access key management.

  • iaas

    Commands used for the full set of supported cloud management tasks.

All IaaS calls are asynchronous. Each CLI command has some common options. Depending on the command prefix, the options can vary. The following table lists these options and their descriptions.

Option Description Required

--base-url <base_url>

Base URL of the Oracle Enterprise Manager Ops Center vServer. https://<ochost>

Yes

--user

User name of the cloud user.

Yes for akm commands only

--password-file|-p <pw_file>

Path to the file storing the password of the cloud user.

Yes for akm commands only

--access-key-file|-a <access_key_file>

Path to the file storing the access key.

Yes for iaas commands only

--help|-h

Explains the command usage and its arguments.

No

--header|-H

Adds a header row to the output.

No

--sep <separator>

Specifies a column separator character. The default separator is TAB.

No

--xml

Displays the output in XML format. The default output is in tabular format.

No

--verbose|-v

Starts the command in verbose mode.

No

--debug|-D

Starts the command in debug mode.

No


C.4.2 Getting Started

Before you can use the vDC infrastructure as an Iaas user, you must create an access key, which is used for authenticating cloud web service requests for an account.

User management is provided by a central service within Exalogic Control. The central entry point for cloud API or CLI requests is the cloud web service. The cloud web service handles the authentication and authorization of the calling user, and it manages access keys.

An access key consists of an ID, a private key, a public key, and an authentication target account. The private key is used on the client side to sign HTTP requests. The cloud web service uses the public key to verify incoming HTTP requests and to authenticate the calling user. After creation, the private key is provided to the user. The Cloud User is responsible for limiting access to the private key.

Run the following commands to get started:

  1. View Accounts' information for a cloud user by using the akm-describe-accounts command, as in the following example:

    ./akm-describe-accounts --base-url https://<localhost>/ --user testuser --password-file ~/pwd.file

    This command displays the user name of the specified cloud user along with the account ID, the name, and the description of each account available for that cloud user.

  2. Create an access key by using the akm-create-access-key command, as in the following example:

    ./akm-create-access-key --base-url https://<localhost>/ --user User1 --password-file ~/pwd.file --account ACC-4b83b85e-592c-45a1-ba71-3bd0774fbd0e --access-key-file ~/ak.file

    This command creates an access key and returns an access key identifier, such as AK_32.

    Note:

    You can obtain the account ID from the output of the akm-describe-accounts command.

  3. View information about an access key by using the akm-describe-access-keys command, as in the following example:

    akm-describe-access-keys --base-url https://<localhost>/ --user User1 --password-file ~/pwd.file

C.4.3 Describing vDC Capabilities

You can describe the vDC capabilities for an account by using the iaas-describe-vdc-capabilities command, as in the following example:

./iaas-describe-vdc-capabilities --base-url https://<localhost>/ -a ak.file -H

This command displays information about the following:

  • Virtualization type, such as OVM

  • Virtualization version, such as OVM 3.0.2

  • Processor architecture

  • Distribution group support

C.4.4 Example Procedure: Importing Server Templates

To import a Server Template, complete the following steps:

  1. Ensure that the Server Template is on a network that is available to the VM hosting the Enterprise Controller.

  2. Register a Server Template from URL by using the iaas-create-server-template-from-url command, as in the following example:

    ./iaas-create-server-template-from-url --base-url https://<localhost>/ --access-key-file ak.file --name myST --url http://<host_name_of_ZFS_appliance>/common/images/OVM.tar.gz

    Upon success, this command returns the Server Template ID and loads the Server Template in an account. For example, TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03.

  3. View information about the newly registered Server Template by using the iaas-describe-server-templates command, as in the following example:

    ./iaas-describe-server-templates --base-url https://<localhost>/ --access-key-file ak.file -H

    Upon success, this command returns a list of the Server Templates available in the account corresponding to the access key file. Each of the Server Templates listed contains the ID, name, description, status, size, and image type. The output also indicates whether the Server Template is public or read-only.

  4. Create a tag on the newly registered Server Template by using the iaas-create-tags command, as in the following example:

    ./iaas-create-tags --base-url https://<localhost>/ -a ak.file --id TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03 --tags myTag=myTagValue

    This command adds or overwrites tags to the specified resource (Server Template, in this example). The command does not return any value.

    Note:

    A tag is a key/value pair that can be attached to a resource. The key and the value are strings. All entities in Enterprise Manager Ops Center are managed resources that can be tagged in a resource using their tag names or tag values. Tags are used to bind user-specific information to entities.

  5. View information about the Server Template that has an associated tag. Run the iaas-describe-tags command, as in the following example:

    ./iaas-describe-tags --base-url https://<localhost>/ -a ak.file --ids TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03

    This command returns the name and value of the tag associated with the specified Server Template.

C.4.5 Example Procedure: Creating Key Pairs for an Account

Complete the following tasks:

  1. Create a key pair for an account, and store the private key in a specified key file by using the iaas-create-key-pair command, as in the following example:

    ./iaas-create-key-pair --base-url https://<localhost>/ -a ak.file --key-name myKeyPair --key-file myKeyFile

    This command returns the ID of the key pair. For example, dx a9:60:cb:88:4a:42:2d:c5:d4:f1:23:63:64:54:d9:0a:e0:c5:a5:9e.

  2. View information about key pairs in an account by using the iaas-describe-key-pairs command, as in the following example:

    ./iaas-describe-key-pairs --base-url https://<localhost>/ -a ak.file

    This command returns the list of existing key pairs and their attributes. If no key pairs are found, the response is empty.

C.4.6 Example Procedure: Creating Private Virtual Networks

Complete the following tasks:

  1. Create a private virtual network (vNet) for the account by using the iaas-create-vnet command, as in the following example:

    ./iaas-create-vnet --base-url https://<localhost>/ --access-key-file ak.file --name vnet1

    Upon success, this command returns an ID of the newly created vNet. For example, VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad.

  2. View information about the newly created private vNet by using the iaas-describe-vnets command, as in the following example:

    ./iaas-describe-vnets --base-url https://<localhost>/ -a ak.file --ids VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad

    This command returns information about the specified private vNet. The output includes the name, ID, status, and IP address.

  3. Create a tag on the newly created vNet by using the iaas-create-tags command, as in the following example:

    ./iaas-create-tags --base-url https://<localhost>/ -a ak.file --id VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad --tags myTag=myTagValue

    This command adds or overwrites tags to the specified resource (vNet, in this example). The command does not return any value.

    Note:

    A tag is a key/value pair that can be attached to a resource. The key and the value are strings. All entities in Enterprise Manager Ops Center are managed resources that can be tagged in a resource using their tag names or tag values. Tags are used to bind user-specific information to entities.

  4. View information about the newly created vNet with its associated tag. Run the iaas-describe-tags command, as in the following example:

    ./iaas-describe-tags --base-url https://<localhost>/ -a ak.file --ids VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad

    This command returns the name and value of the newly created tag associated with the vNet.

C.4.7 Example Procedure: Allocating IP Addresses for vServers

You must allocate a set of IP addresses from the private virtual network (vNet) for vServers to be created later.

Complete the following tasks:

  1. Allocate a set of IP addresses from the private vNet by using the iaas-allocate-ip-addresses command, as in the following example:

    ./iaas-allocate-ip-addresses --base-url https://<localhost>/ -a ak.file --vnet VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad --num 2

    This command allocates two IP addresses from the private vNet VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad. For example, 192.168.0.2 and 192.168.0.3. You can assign one of these IP addresses when creating a vServer at a later time.

  2. View information about the newly allocated IP addresses by using the iaas-describe-ip-addresses command, as in the following example:

    ./iaas-describe-ip-addresses --base-url https://<localhost>/ -a ak.file --filters VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad

    This command returns the IP addresses allocated from the specified vNet.

C.4.8 Example Procedure: Creating Distribution Groups

Distribution groups are necessary for anti-affinity scaling in an Oracle VM Server pool.

Complete the following tasks:

  1. Create a distribution group by using the iaas-create-distribution-group command, as in the following example:

    ./iaas-create-distribution-group --base-url https://<localhost>/ -a ak.file --name Dept1-distgrp1

    This command returns the ID of the distribution group. For example, DG-068ae84c-d0fc-406d-aa37-0be4f88d411c.

  2. View information about the newly created distribution group by using the iaas-describe-distribution-groups command, as in the following example:

    ./iaas-describe-distribution-groups --base-url https://<localhost>/ -a ~/ak.file --ids DG-068ae84c-d0fc-406d-aa37-0be4f88d411c -H

    This command returns the attributes of the specified distribution group, which is empty at this time.

C.4.9 Example Procedure: Creating Volumes

Complete the following tasks:

  1. Create a volume by using the iaas-create-volume command, as in the following example:

    ./iaas-create-volume --base-url https://<localhost>/ --access-key-file ak.file --name Volume1 --size 16

    This command creates a Volume named Volume1 of size 16 GB. It returns the ID of the newly created volume. For example, VOL-f23a8ba1-ec55-4159-bbdf-de220d18a1c4.

  2. View information about the newly created volume by using the iaas-describe-volumes command, as in the following example:

    ./iaas-describe-volumes --base-url https://<localhost>/ -a ak.file --ids VOL-f23a8ba1-ec55-4159-bbdf-de220d18a1c4

    This command returns the ID of the specified volume, its name, status, and size.

Note:

After creating a volume, you must partition the volume using fdisk and create a file system using mkfs on the first vServer that is created with the volume. On the vServer, the volume appears as a disk (/dev/hdX or /dev/xvdX). After the volume is partitioned and file system created, you must mount it using the /etc/fstab file on the vServer to make the file system accessible.

C.4.10 Example Procedure: Importing Volumes

If you wish to import a volume from an existing URL instead of creating a new volume, complete the following tasks:

  1. Import a volume by using the iaas-import-volume command, as in the following example:

    ./iaas-import-volume --base-url https://<localhost>/ -a ak.file --name Volume2 --url http://ovm.oracle.com/volume-image/volume.img

    This command returns the ID of the volume that was imported as Volume2. For example, VOL-e9afec8c-dbe2-4e03-8561-15716650b81e.

  2. View information about Volume2 by using the iaas-describe-volumes command, as in the following example:

    ./iaas-describe-volumes --base-url https://<localhost>/ -a ak.file --ids VOL-e9afec8c-dbe2-4e03-8561-15716650b81e

    This command returns the ID of the specified volume, its name, status, and size.

C.4.11 Example Procedure: Creating vServers

You can create vServers using one of the following commands:

When you create multiple vServers, only automatic IP address assignment is possible, and a suffix is added to the vServer name for each vServer. When you create a single vServer, you can assign a static IP address. In this case, a suffix is not added to the name of the vServer.

Example Procedure: Creating Multiple vServers

  1. Create two vServers by using the iaas-run-vservers command, as in the following example:

    ./iaas-run-vservers --base-url https://<localhost>/ -a ~/ak.file --vnets VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad --key-name myKeyPair --name myvserver --num 2 --server-template-id TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03 --dist-group DG-068ae84c-d0fc-406d-aa37-0be4f88d411c --vserver-type 457

    In this example, you are creating two vServers with the following attributes:

    • Name: myvserver

    • Private vNet to be associated with: VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad

      Note:

      In this example, the vServers are associated with a single private vNet. However, you can associate a vServer with multiple vNets.

    • Server Template to be used: TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03

    • Distribution group to be associated with: DG-068ae84c-d0fc-406d-aa37-0be4f88d411c

    This command creates the specified vServers and returns their ID. For example, VSRV-d6800889-f59b-4798-a57d-3f9f31b0cf1c and VSRV-d6500889-f59b-4567-a65g-3f9f31b0se1d. The vServers are created and started. The IP addresses are assigned to the vServers automatically.

  2. View information about the newly created vServer vserver1 by using the iaas-describe-vservers command, as in the following example:

    ./iaas-describe-vservers --base-url https://<localhost>/ -a ak.file --ids VSRV-d6800889-f59b-4798-a57d-3f9f31b0cf1c VSRV-d6500889-f59b-4567-a65g-3f9f31b0se1d

    Alternatively, you can view information about all vServers by using the iaas-describe-vservers command, as in the following example:

    ./iaas-describe-vservers --base-url https://<localhost>/ -a ak.file

  3. Create a tag on the newly created vServers by using the iaas-create-tags command, as in the following example:

    ./iaas-create-tags --base-url https://<localhost>/ -a ak.file --id VSRV-d6800889-f59b-4798-a57d-3f9f31b0cf1c VSRV-d6500889-f59b-4567-a65g-3f9f31b0se1d --tags myTag=myTagValue

    This command adds or overwrites tags to the specified resource (vServer, in this example). The command does not return any value.

    Note:

    A tag is a key/value pair that can be attached to a resource. The key and the value are strings. All entities in Enterprise Manager Ops Center are managed resources that can be tagged in a resource using their tag names or tag values. Tags are used to bind user-specific information to entities.

  4. View information about the newly created vServers with their associated tag. Run the iaas-describe-tags command, as in the following example:

    ./iaas-describe-tags --base-url https://<localhost>/ -a ak.file --ids VSRV-d6800889-f59b-4798-a57d-3f9f31b0cf1c VSRV-d6500889-f59b-4567-a65g-3f9f31b0se1d

    This command returns the name and value of the newly created tag associated with the vServers.

Example Procedure: Creating a Single vServer

To create a single vServer, complete the following steps:

  1. Create a vServer by using the iaas-run-vserver command, as in the following example:

    ./iaas-run-vserver --base-url https://<localhost>/ -a ~/ak.file --vnets VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad --key-name myKeyPair --name vserver1 --server-template-id TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03 --dist-group DG-068ae84c-d0fc-406d-aa37-0be4f88d411c --ip-addresses 192.168.0.2 --vserver-type 457

    In this example, you are creating a vServer with the following attributes:

    • Name: vserver1

    • Private vNet to be associated with: VNET-350c9c3f-0ee5-41be-917e-ebbaed0fa4ad

      Note:

      In this example, the vServer is associated with a single private vNet. However, you can associate a vServer with multiple vNets.

    • Server Template to be used: TMPL-aaaaaaa8-bbb4-ccc4-ddd4-eeeeeeeeee03

    • Distribution group to be associated with: DG-068ae84c-d0fc-406d-aa37-0be4f88d411c

    • IP address to use: 192.168.0.2

    This command creates the specified vServer and returns its ID. For example, VSRV-0fb57293-347c-4717-96ef-6dd23154596f. The vServer is created and started.

  2. View information about the newly created vServer vserver1 by using the iaas-describe-vservers command, as in the following example:

    ./iaas-describe-vservers --base-url https://<localhost>/ -a ak.file --ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

  3. Create a tag on the newly created vServer by using the iaas-create-tags command, as in the following example:

    ./iaas-create-tags --base-url https://<localhost>/ -a ak.file --id VSRV-0fb57293-347c-4717-96ef-6dd23154596f --tags myTag=myTagValue

    This command adds or overwrites tags to the specified resource (vServer, in this example). The command does not return any value.

    Note:

    A tag is a key/value pair that can be attached to a resource. The key and the value are strings. All entities in Enterprise Manager Ops Center are managed resources that can be tagged in a resource using their tag names or tag values. Tags are used to bind user-specific information to entities.

  4. View information about the newly created vServer with its associated tag. Run the iaas-describe-tags command, as in the following example:

    ./iaas-describe-tags --base-url https://<localhost>/ -a ak.file --ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

    This command returns the name and value of the newly created tag associated with the vServer.

C.4.12 Example Procedure: Stopping a vServer

To stop a running vServer, run the iaas-stop-vservers command, as in the following example:

./iaas-stop-vservers --base-url https://<localhost>/ -a ak.file --vserver-ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

This command stops the specified vServer. It does not return any value.

C.4.13 Example Procedure: Attaching Volume to vServer

To attach a volume to a vServer, complete the following steps:

  1. Ensure that the vServer is stopped.

  2. Attach a volume to the vServer by using the iaas-attach-volumes-to-vserver command, as in the following example:

    ./iaas-attach-volumes-to-vserver --base-url https://<localhost>/ -a ~/ak.file -vserver-id VSRV-0fb57293-347c-4717-96ef-6dd23154596f --volume-ids VOL-f23a8ba1-ec55-4159-bbdf-de220d18a1c4

    This command attaches the specified volume to the specified vServer. It does not return any value. To verify that a vServer is stopped, check the status of the vserver using the iaas-describe-vservers command.

  3. After attaching the volume to the vServer, start the vServer by using the iaas-start-vservers command, as in the following example:

    ./iaas-start-vservers --base-url https://<localhost>/ -a ak.file --vserver-ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

    This command starts the specified vServer. It does not return any value.

C.4.14 Example Procedure: Detaching Volume from vServer

If you wish to detach a volume from a vServer, complete the following steps:

  1. Ensure that the vServer is stopped.

  2. Detach a volume from the vServer by using the iaas-detach-volumes-from-vserver command, as in the following example:

    ./iaas-detach-volumes-from-vserver --base-url https://<localhost>/ -a ~/ak.file -vserver-id VSRV-0fb57293-347c-4717-96ef-6dd23154596f --volume-ids VOL-f23a8ba1-ec55-4159-bbdf-de220d18a1c4

    This command detaches the specified volume from the specified vServer. It does not return any value.

  3. After detaching the volume from the vServer, start the vServer by using the iaas-start-vservers command, as in the following example:

    ./iaas-start-vservers --base-url https://<localhost>/ -a ak.file --vserver-ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

    This command starts the specified vServer. It does not return any value.

C.4.15 Example Procedure: Creating Snapshot from Volume

To create a Snapshot from a volume, complete the following steps:

  1. Before creating a Snapshot from a volume, verify that the volume is not attached to any vServers. If the volume is attached to a vServer, you must stop the vServer by using the iaas-stop-vservers command, as in the following example:

    ./iaas-stop-vservers --base-url https://<localhost>/ -a ak.file --vserver-ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

    This command stops the specified vServer. It does not return any value.

  2. Create a Snapshot from a volume by using the iaas-create-snapshot command, as in the following example:

    ./iaas-create-snapshot --base-url https://<localhost>/ -a ak.file --volume-id VOL-f23a8ba1-ec55-4159-bbdf-de220d18a1c4 --name mySnapshot

    This command creates a Snapshot from the specified volume. It returns the Snapshot ID. For example, SNAP-7a717e39-fe67-4573-a93d-889b3446176b.

  3. View information about the newly created Snapshot mySnapshot by using the iaas-describe-snapshots command, as in the following example:

    ./iaas-describe-snapshots --base-url https://<localhost>/ -a ak.file -H

    This command returns a list of all Snapshots in the account.

  4. After creating a Snapshot, start the vServer by using the iaas-start-vservers command, as in the following example:

    ./iaas-start-vservers --base-url https://<localhost>/ -a ak.file --vserver-ids VSRV-0fb57293-347c-4717-96ef-6dd23154596f

    This command starts the specified vServer. It does not return any value.

C.4.16 Example Procedure: Creating Volume from Snapshot

To create a volume from Snapshot, complete the following tasks:

  1. Create a volume by using the iaas-create-volume command, as in the following example:

    ./iaas-create-volume --base-url https://<localhost>/ --access-key-file ak.file --name Volume2 --snapshot-id SNAP-7a717e39-fe67-4573-a93d-889b3446176b

    This command creates a volume named Volume2 from the specified Snapshot. It returns the Volume ID. For example, VOL-g23a8ba1-ec55-4159-bbdf-de220d18a1b7.

  2. View information about the newly created volume by using the iaas-describe-volumes command, as in the following example:

    ./iaas-describe-volumes --base-url https://<localhost>/ -a ak.file --ids VOL-g23a8ba1-ec55-4159-bbdf-de220d18a1b7

    This command returns the ID of the specified volume, its name, status, and size.