Oracle® Enterprise Manager Ops Center [1] Cloud Infrastructure API and CLI Reference Guide 12c Release 2 (12.2.2.0.0) E38530-02 December 2014 Oracle Enterprise Manager Ops Center Cloud Infrastructure API and CLI Reference Guide, 12c Release 2 (12.2.2.0.0) E38530-02 Copyright © 2007, 2014, Oracle and/or its affiliates. All rights reserved. Primary Author: Karen Orozco This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle. Contents Preface............................................................................................................................................................... xv Audience..................................................................................................................................................... xv Documentation Accessibility................................................................................................................... xv Related Documents................................................................................................................................... xv Conventions............................................................................................................................................... xv 1 Introduction Overview of Virtual Datacenter Management................................................................................... 1-1 How APIs and CLI Work........................................................................................................................ 1-2 Overview of the Functionality............................................................................................................... 1-3 2 Getting Started Prerequisites.............................................................................................................................................. 2-1 Installation................................................................................................................................................. 2-1 Cloud Infrastructure API.................................................................................................................. 2-1 Cloud Infrastructure Java Client API.............................................................................................. 2-1 Cloud Infrastructure CLI.................................................................................................................. 2-2 Next Steps.................................................................................................................................................. 2-3 3 Managing Resources Overview of Cloud User Resources...................................................................................................... 3-1 Status of Account Resources............................................................................................................. 3-2 Managing Account Access...................................................................................................................... 3-3 Creating an Access Key..................................................................................................................... 3-4 Viewing Access Key Information.................................................................................................... 3-4 Deleting an Access Key..................................................................................................................... 3-5 Viewing vDC Capabilities..................................................................................................................... 3-5 Managing Virtual Networks.................................................................................................................. 3-6 Creating a vNet................................................................................................................................... 3-6 Deleting a vNet................................................................................................................................... 3-7 Viewing vNet Information................................................................................................................ 3-7 Managing vIP Addresses........................................................................................................................ 3-8 Allocating a vIP Address.................................................................................................................. 3-8 Deallocating a vIP Address.............................................................................................................. 3-8 Viewing vIP Addresses..................................................................................................................... 3-9 iii Managing Server Templates.................................................................................................................. 3-9 Uploading a Server Template from a vServer............................................................................ 3-10 Uploading a Server Template from a URL.................................................................................. 3-11 Uploading a Server Template from an Assembly...................................................................... 3-11 Deleting a Server Template............................................................................................................ 3-12 Viewing Server Template Information........................................................................................ 3-12 Managing Storage................................................................................................................................. 3-13 Creating a Volume.......................................................................................................................... 3-13 Deleting a Volume.......................................................................................................................... 3-14 Viewing Volume Information....................................................................................................... 3-14 Attaching a Volume to a vServer.................................................................................................. 3-15 Detaching a Volume from a vServer............................................................................................ 3-15 Importing a Volume........................................................................................................................ 3-16 Creating a Snapshot........................................................................................................................ 3-16 Deleting a Snapshot........................................................................................................................ 3-17 Viewing Snapshot Information..................................................................................................... 3-17 Managing Distribution Groups.......................................................................................................... 3-18 Creating a Distribution Group...................................................................................................... 3-19 Deleting a Distribution Group...................................................................................................... 3-19 Viewing Distribution Group Information................................................................................... 3-20 Managing vServers............................................................................................................................... 3-20 Viewing vServer Types.................................................................................................................. 3-21 Creating a vServer........................................................................................................................... 3-21 Deleting a vServer........................................................................................................................... 3-23 Viewing vServer Information........................................................................................................ 3-23 Viewing vServer Metrics................................................................................................................ 3-24 Stopping a vServer.......................................................................................................................... 3-25 Starting a vServer............................................................................................................................ 3-25 Rebooting a vServer........................................................................................................................ 3-25 Sending a Message to a vServer.................................................................................................... 3-26 Receiving a Message from a vServer............................................................................................ 3-26 Managing Key Pairs.............................................................................................................................. 3-27 Creating a Key Pair......................................................................................................................... 3-27 Importing a Key Pair...................................................................................................................... 3-28 Deleting a Key Pair......................................................................................................................... 3-28 Viewing Key Pair Information...................................................................................................... 3-28 Managing Attributes of an Account Resource................................................................................. 3-29 Viewing Attributes of an Account Resource............................................................................... 3-29 Modifying Attributes of an Account Resource........................................................................... 3-30 Managing Tags....................................................................................................................................... 3-30 Creating a Tag.................................................................................................................................. 3-30 Removing a Tag............................................................................................................................... 3-31 Viewing Tag Information............................................................................................................... 3-31 4 Cloud Infrastructure API Reference Overview of the Cloud Infrastructure API.......................................................................................... 4-1 Cloud Infrastructure API Requests...................................................................................................... 4-1 iv Required Web Service HTTP Request Parameters........................................................................ 4-2 Signing a Web Service Request........................................................................................................ 4-2 List of Actions........................................................................................................................................... 4-4 AllocateIpAddressesRequest............................................................................................................ 4-5 AttachVolumesToVserverRequest.................................................................................................. 4-7 CreateAccessKeyAsObjectRequest.................................................................................................. 4-9 CreateAccessKeyToFileRequest.................................................................................................... 4-10 CreateDistributionGroupRequest................................................................................................. 4-12 CreateKeyPairAsObjectRequest.................................................................................................... 4-14 CreateKeyPairToFileRequest......................................................................................................... 4-15 CreateSnapshotRequest.................................................................................................................. 4-16 CreateTagsRequest.......................................................................................................................... 4-18 CreateVnetRequest.......................................................................................................................... 4-20 CreateVolumeRequest.................................................................................................................... 4-22 DeleteAccessKeyRequest............................................................................................................... 4-24 DeleteDistributionGroupRequest................................................................................................. 4-25 DeleteKeyPairRequest.................................................................................................................... 4-26 DeleteSnapshotRequest.................................................................................................................. 4-27 DeleteTagsRequest.......................................................................................................................... 4-28 DeleteVnetRequest.......................................................................................................................... 4-30 DeleteVolumeRequest.................................................................................................................... 4-31 DeregisterServerTemplateRequest............................................................................................... 4-32 DescribeAccessKeysRequest......................................................................................................... 4-33 DescribeAccountsRequest.............................................................................................................. 4-35 DescribeAttributesRequest............................................................................................................ 4-37 DescribeDistributionGroupsRequest........................................................................................... 4-39 DescribeIpAddressesRequest........................................................................................................ 4-41 DescribeKeyPairsRequest.............................................................................................................. 4-43 DescribeServerTemplatesRequest................................................................................................ 4-45 DescribeSnapshotsRequest............................................................................................................ 4-47 DescribeTagsRequest...................................................................................................................... 4-49 DescribeVdcCapabilitiesRequest.................................................................................................. 4-51 DescribeVnetsRequest.................................................................................................................... 4-53 DescribeVolumesRequest.............................................................................................................. 4-55 DescribeVserverMetricsRequest................................................................................................... 4-57 DescribeVserversRequest............................................................................................................... 4-59 DescribeVserverTypesRequest...................................................................................................... 4-62 DetachVolumesFromVserverRequest.......................................................................................... 4-64 ImportKeyPairRequest................................................................................................................... 4-66 ImportVolumeRequest................................................................................................................... 4-68 ModifyAttributesRequest.............................................................................................................. 4-70 RebootVserversRequest.................................................................................................................. 4-72 ReceiveMessageFromVserverRequest......................................................................................... 4-73 RegisterAccessKeyRequest............................................................................................................ 4-75 RegisterKeyPairRequest................................................................................................................. 4-77 RegisterServerTemplateFromUrlRequest.................................................................................... 4-79 RegisterServerTemplateFromVserverRequest............................................................................ 4-81 v RegisterServerTemplatesFromAssemblyRequest...................................................................... 4-83 ReleaseIpAddressesRequest.......................................................................................................... 4-85 RunVserverRequest........................................................................................................................ 4-87 RunVserversRequest....................................................................................................................... 4-90 SendMessagesToVserverRequest................................................................................................. 4-93 StartVserversRequest...................................................................................................................... 4-95 StopVserversRequest...................................................................................................................... 4-96 TerminateVserversRequest............................................................................................................ 4-98 Data Types............................................................................................................................................ 4-100 AccountIdType.............................................................................................................................. 4-101 DescribeAccessKeysResultItem.................................................................................................. 4-102 DescribeAccountsResultItem...................................................................................................... 4-103 DescribeDistributionGroupsResultItem.................................................................................... 4-104 DescribeIpAddressesResultItem................................................................................................. 4-105 DescribeKeyPairsResultItem....................................................................................................... 4-106 DescribeServerTemplatesResultItem......................................................................................... 4-107 DescribeSnapshotsResultItem..................................................................................................... 4-108 DescribeTagsResultItem............................................................................................................... 4-109 DescribeVdcCapabilitiesResultItem........................................................................................... 4-110 DescribeVnetsResultItem............................................................................................................. 4-111 DescribeVolumesResultItem....................................................................................................... 4-112 DescribeVserverMetricsResultItem............................................................................................ 4-113 DescribeVserversResultItem........................................................................................................ 4-114 DescribeVserverTypesResultItem............................................................................................... 4-116 DistributionGroupIdType............................................................................................................ 4-117 FilterItem........................................................................................................................................ 4-118 GenericString................................................................................................................................. 4-119 HostnameType.............................................................................................................................. 4-120 Message.......................................................................................................................................... 4-121 PositiveInteger............................................................................................................................... 4-122 ResourceAttribute......................................................................................................................... 4-123 ResourceIdType............................................................................................................................. 4-124 SnapshotIdType............................................................................................................................. 4-125 ServerTemplateIdType................................................................................................................. 4-126 TagType.......................................................................................................................................... 4-127 URLType........................................................................................................................................ 4-128 VnetIdType.................................................................................................................................... 4-129 VolumeIdType............................................................................................................................... 4-130 VserverIdType............................................................................................................................... 4-131 5 Cloud Infrastructure CLI Reference Common Command Options................................................................................................................. 5-1 Examples............................................................................................................................................. 5-2 List of Commands.................................................................................................................................... 5-4 akm-create-access-key....................................................................................................................... 5-5 akm-delete-access-key....................................................................................................................... 5-9 akm-describe-access-keys.............................................................................................................. 5-12 vi akm-describe-accounts................................................................................................................... 5-15 iaas-allocate-ip-addresses.............................................................................................................. 5-18 iaas-attach-volumes-to-vserver..................................................................................................... 5-21 iaas-create-distribution-group....................................................................................................... 5-23 iaas-create-key-pair......................................................................................................................... 5-26 iaas-create-server-template-from-assembly................................................................................ 5-28 iaas-create-server-template-from-url........................................................................................... 5-31 iaas-create-server-template-from-vserver................................................................................... 5-34 iaas-create-snapshot........................................................................................................................ 5-37 iaas-create-tags................................................................................................................................ 5-40 iaas-create-vnet................................................................................................................................ 5-43 iaas-create-volume.......................................................................................................................... 5-46 iaas-delete-distribution-group...................................................................................................... 5-49 iaas-delete-key-pair......................................................................................................................... 5-51 iaas-delete-server-template............................................................................................................ 5-53 iaas-delete-snapshot........................................................................................................................ 5-55 iaas-delete-tags................................................................................................................................ 5-57 iaas-delete-vnet................................................................................................................................ 5-60 iaas-delete-volume.......................................................................................................................... 5-62 iaas-describe-attributes................................................................................................................... 5-64 iaas-describe-distribution-groups................................................................................................. 5-67 iaas-describe-ip-addresses............................................................................................................. 5-69 iaas-describe-key-pairs................................................................................................................... 5-72 iaas-describe-server-templates...................................................................................................... 5-75 iaas-describe-snapshots.................................................................................................................. 5-78 iaas-describe-tags............................................................................................................................ 5-80 iaas-describe-vdc-capabilities........................................................................................................ 5-83 iaas-describe-vnets.......................................................................................................................... 5-86 iaas-describe-volumes.................................................................................................................... 5-89 iaas-describe-vserver-metrics........................................................................................................ 5-92 iaas-describe-vservers..................................................................................................................... 5-95 iaas-describe-vserver-types........................................................................................................... 5-98 iaas-detach-volumes-from-vserver............................................................................................. 5-100 iaas-import-key-pair..................................................................................................................... 5-102 iaas-import-volume....................................................................................................................... 5-105 iaas-modify-attributes.................................................................................................................. 5-108 iaas-reboot-vservers...................................................................................................................... 5-111 iaas-receive-message-from-vserver............................................................................................ 5-113 iaas-release-ip-addresses.............................................................................................................. 5-116 iaas-run-vserver............................................................................................................................. 5-119 iaas-run-vservers........................................................................................................................... 5-122 iaas-send-messages-to-vserver.................................................................................................... 5-125 iaas-start-vservers......................................................................................................................... 5-127 iaas-stop-vservers.......................................................................................................................... 5-129 iaas-terminate-vservers................................................................................................................ 5-131 vii A Web Service Client Example Description of Web Service API Requests......................................................................................... A-1 AKM Request..................................................................................................................................... A-1 REQUEST_DATA Specification............................................................................................... A-2 IAAS Request..................................................................................................................................... A-2 REQUEST_IAAS_DATA Specification................................................................................... A-2 SIGNATURE_BLOCK Specification....................................................................................... A-3 IAAS Data Used for Signature................................................................................................. A-3 Sending a Web Service Request........................................................................................................... A-4 Using the Web Browser.................................................................................................................... A-4 Using WGET Utility.......................................................................................................................... A-4 Creating Public and Private Keys........................................................................................................ A-5 Private Key......................................................................................................................................... A-5 Public Key.......................................................................................................................................... A-5 Overview of the WebUtil Application................................................................................................ A-5 How the WebUtil Application Works............................................................................................ A-8 Examples of Web Service Requests..................................................................................................... A-9 Creating an Access Key.................................................................................................................... A-9 Executing actions for an account.................................................................................................. A-10 Viewing All Available Virtual Networks............................................................................. A-10 Viewing Specific Virtual Networks by Using IDs .............................................................. A-11 Viewing Specific Virtual Networks by Using Filters.......................................................... A-12 Creating a Private Virtual Network...................................................................................... A-13 Index viii ix List of Examples 3–1 Creating an access key using the Cloud Infrastructure API................................................. 3-4 3–2 Creating an access key using the Cloud Infrastructure CLI................................................. 3-4 3–3 Viewing access key information using the Cloud Infrastructure API................................ 3-5 3–4 Viewing access key information using the Cloud Infrastructure CLI................................. 3-5 3–5 Deleting an access key information using the Cloud Infrastructure API........................... 3-5 3–6 Deleting an access key information using the Cloud Infrastructure CLI........................... 3-5 3–7 Viewing vDC capabilities using the Cloud Infrastructure API........................................... 3-6 3–8 Viewing vDC capabilities using the Cloud Infrastructure CLI............................................ 3-6 3–9 Creating a vNet using the Cloud Infrastructure API............................................................ 3-7 3–10 Creating a vNet using the Cloud Infrastructure CLI............................................................. 3-7 3–11 Deleting a vNet using the Cloud Infrastructure API............................................................. 3-7 3–12 Deleting a vNet using the Cloud Infrastructure CLI............................................................. 3-7 3–13 Viewing vNet information using the Cloud Infrastructure API.......................................... 3-8 3–14 Viewing vNet information using the Cloud Infrastructure CLI.......................................... 3-8 3–15 Allocating a vIP address using the Cloud Infrastructure API............................................. 3-8 3–16 Allocating a vIP address using the Cloud Infrastructure CLI.............................................. 3-8 3–17 Deallocating a vIP address using the Cloud Infrastructure API......................................... 3-9 3–18 Deallocating a vIP address using the Cloud Infrastructure CLI.......................................... 3-9 3–19 Viewing vIP addresses using the Cloud Infrastructure API................................................ 3-9 3–20 Viewing vIP addresses using the Cloud Infrastructure CLI................................................ 3-9 3–21 Uploading a server template from a vServer using the Cloud Infrastructure API........ 3-10 3–22 Uploading a server template from a vServer using the Cloud Infrastructure CLI........ 3-11 3–23 Uploading a server template from a URL using the Cloud Infrastructure API............. 3-11 3–24 Uploading a server template from a URL using the Cloud Infrastructure CLI............. 3-11 3–25 Uploading a server template from an assembly using the Cloud Infrastructure API... 3-12 3–26 Uploading a server template from an assembly using the Cloud Infrastructure CLI... 3-12 3–27 Deleting a server template using the Cloud Infrastructure API....................................... 3-12 3–28 Deleting a server template using the Cloud Infrastructure CLI....................................... 3-12 3–29 Viewing server template information using the Cloud Infrastructure API.................... 3-13 3–30 Viewing server template information using the Cloud Infrastructure CLI.................... 3-13 3–31 Creating a volume using the Cloud Infrastructure API..................................................... 3-14 3–32 Creating a volume using the Cloud Infrastructure CLI..................................................... 3-14 3–33 Deleting a volume using the Cloud Infrastructure API..................................................... 3-14 3–34 Deleting a volume using the Cloud Infrastructure CLI..................................................... 3-14 3–35 Viewing volume information using the Cloud Infrastructure API.................................. 3-15 3–36 Viewing volume information using the Cloud Infrastructure CLI.................................. 3-15 3–37 Attaching a volume to a vServer using the Cloud Infrastructure API............................. 3-15 3–38 Attaching a volume to a vServer using the Cloud Infrastructure CLI............................. 3-15 3–39 Detaching a volume to a vServer using the Cloud Infrastructure API............................ 3-16 3–40 Detaching a volume to a vServer using the Cloud Infrastructure CLI............................ 3-16 3–41 Importing a volume using the Cloud Infrastructure API.................................................. 3-16 3–42 Importing a volume using the Cloud Infrastructure CLI.................................................. 3-16 3–43 Creating a snapshot using the Cloud Infrastructure API.................................................. 3-17 3–44 Creating a snapshot using the Cloud Infrastructure CLI................................................... 3-17 3–45 Deleting a snapshot using the Cloud Infrastructure API................................................... 3-17 3–46 Deleting a snapshot using the Cloud Infrastructure CLI................................................... 3-17 3–47 Viewing snapshot information using the Cloud Infrastructure API................................ 3-18 3–48 Viewing snapshot information using the Cloud Infrastructure CLI................................ 3-18 3–49 Creating a distribution group using the Cloud Infrastructure API.................................. 3-19 3–50 Creating a distribution group using the Cloud Infrastructure CLI.................................. 3-19 3–51 Deleting a distribution group using the Cloud Infrastructure API.................................. 3-19 3–52 Deleting a distribution group using the Cloud Infrastructure CLI.................................. 3-19 3–53 Viewing distribution groups information using the Cloud Infrastructure API............. 3-20 3–54 Viewing distribution groups information using the Cloud Infrastructure CLI............. 3-20 x