Top Banner
Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider Reference Guide vRealize Automation 7.3 TECHNICAL WHITE PAPER AUG 15, 2017 VERSION 1.2
19

vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

Apr 23, 2018

Download

Documents

lamnga
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Creating a vRealize

Orchestrator Package for a

vRealize Automation Third

Party IPAM Service Provider

Reference Guide

vRealize Automation 7.3

T E C H N I C A L W H I T E P A P E R

A U G 1 5 , 2 0 1 7

V E R S I O N 1 . 2

Page 2: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

2

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Table of Contents Revision History .............................................................................................................................. 3

Introduction ...................................................................................................................................... 4

Workflow and Machine Allocation .............................................................................................. 4

Workflow and Action Definitions .................................................................................................... 5

Workflow Definitions .................................................................................................................. 5

Action Definitions ....................................................................................................................... 7

Definition Parameters....................................................................................................................... 8

Register a Third-Party IPAM Endpoint ......................................................................................... 16

Procedure – Sample Flow REST API Calls to vRealize Automation ........................................ 16

Transaction Support ....................................................................................................................... 18

Gateway Allocation for Routed and NAT Networks ..................................................................... 18

Address Spaces .............................................................................................................................. 18

Hidden Objects for Routed and NAT Networks ............................................................................ 18

Network Scale for Routed and NAT Networks ............................................................................. 18

Error Handling ............................................................................................................................... 19

Testing and Additional References ................................................................................................ 19

Page 3: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

3

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Revision History

DATE VERSION DESCRIPTION

May 23, 2017 1.0 DRAFT version document for vRA 7.3.

August 10, 2017 1.1 Released.

August 15, 2017 1.2 Minor updates.

Page 4: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

4

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Introduction

This document provides a reference for third party IPAM providers for creating vRealize Orchestrator packages using the vRealize Orchestrator IPAM package SDK. This information in this document is for the following products and versions.

PRODUCT VERSION

vRealize Orchestrator 7.3

vRealize Automation 7.3

The information in this document that applies to external network profiles is also applicable to vRealize Orchestrator 7.1 and greater and vRealize Automation 7.1 and greater. Information applicable to routed network profiles is also applicable to vRealize Orchestrator 7.2 and greater and vRealize Automation 7.2 and greater.

The information in this document that applies to NAT network profiles and the updated vRealize Automation endpoint configuration service (ECS) applies to vRealize Orchestrator 7.3 and and vRealize Automation 7.3.

Workflow and Machine Allocation

The vRealize Automation IPAM service communicates with third-party IPAM service providers through vRealize Orchestrator workflows. To integrate with vRealize Automation IPAM, you must provide the vRealize Orchestrator administrator with a vRealize Orchestrator plug-in or package that includes implementations of required workflows and that registers the external IPAM provider with vRealize Automation. vRealize Automation supplies a vRealize Orchestrator IPAM package SDK that includes workflow stubs for you to implement.

Machine allocation occurs in two stages.

1. Machine allocation allocates a reservation and creates a machine record in the database.

2. Network allocation allocates the machine networks and IP addresses.

During network allocation, the machine record already exists in the database and machine properties are reconciled and stored in the database. vRealize Automation then forwards this information to the provider workflow.

Note: For general information about developing and implementing vRealize Orchestrator workflows, see Developing with VMware vRealize Orchestrator in the vRealize Orchestrator 7.1 or later at docs.vmware.com.

Page 5: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

5

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Workflow and Action Definitions

The following workflow and action definitions are supported for a third-party IPAM service and should be delivered in a vRealize Orchestrator package.

Workflow Definitions

OPERATION NAME

DESCRIPTION INPUT OUTPUT REQUIRED

Register IPAM endpoint

Register a third-party IPAM endpoint with vRealize Automation and optionally create IPAM endpoints of that type within vRealize Automation. This workflow is not called by vRealize Automation and is invoked manually from the vRealize Orchestrator client.

• vRAEndpoint: vRealize Automation URL, user name, and password to call back into vRealize Automation.

• Endpoint: Provider endpoint name, credentials, and custom properties when optionally creating an endpoint instance.

None Yes

Get Address Spaces

Get a list of address spaces from the IPAM endpoint.

• Endpoint: IPAM endpoint.

• PagingAndSorting: Paging and sorting.

• AdditionalFilter: String (additional filter in the provider-specific format).

AddressSpaces: Array<AddressSpace>

No

Page 6: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

6

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

OPERATION NAME

DESCRIPTION INPUT OUTPUT REQUIRED

Get IP Ranges

Get a list of IP ranges from the IPAM endpoint.

• Endpoint: IPAM endpoint.

• PagingAndSorting: Paging and sorting.

• AdditionalFilter: String (additional filter in the provider-specific format).

• IdCollection: Array<String> (optional collection of range IDs).

• IsIPBlock: Boolean. When set to true, only IP blocks are returned.

IPRanges: Array<IPRange>

Yes

Create IP Ranges

Create a number of IP ranges within the same address space for an on-demand network.

This may include creating address spaces.

• Endpoint: IPAM endpoint.

• CreateIPRangeRequests: Array<CreateIPRangeRequest>

CreateIPRangeResults: Array<CreateIPRangeResult>

Yes

Delete IP Ranges

Delete a number of IP ranges for an on-demand network. This may include deleting address spaces as well.

This must be an idempotent operation to allow for easier handling (for example, retries) of partial failure.

• Endpoint: IPAM endpoint.

• DeleteIPRangeRequests: Array<DeleteIPRangeRequest>

DeleteIPRangeResults: Array<DeleteIPRangeResult>

Yes

Allocate

Allocate a block of IP addresses from the IPAM endpoint.

• Endpoint: IPAM endpoint.

• AllocationRequests: Array<AllocationRequest>

• Resource: Resource (optional).

AllocationResults: Array<AllocationResult>

Yes

Page 7: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

7

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

OPERATION NAME

DESCRIPTION INPUT OUTPUT REQUIRED

Release

Release allocated IP addresses from the IPAM endpoint.

• Endpoint: IPAM endpoint.

• ReleaseRequests: Array<ReleaseRequest>

• Resource: Resource (optional).

ReleaseResults: Array<ReleaseResult>

Yes

Action Definitions

vRealize Automation calls the Get Address Spaces and Get IP Ranges actions from the Edit Network Profile user interface in vRealize Automation. To improve the performance of the Edit Network Profile page, the IPAM service supports executing these calls as actions instead of workflows. Because workflows are executed asynchronously, they take more time to process. If an action and workflow are both defined for an operation, vRealize calls the action.

OPERATION NAME

DESCRIPTION INPUT OUTPUT REQUIRED

Get Address Spaces

Get a page of address spaces from the IPAM endpoint.

• Endpoint: IPAM endpoint.

• PagingAndSorting: Paging and sorting.

• AdditionalFilter: String (additional filter in the provider-specific format).

AddressSpaces: Array<AddressSpace>

No

Get IP Ranges

Get a page of IP ranges from the IPAM endpoint.

• Endpoint: IPAM endpoint.

• PagingAndSorting: Paging and sorting.

• AdditionalFilter: String (additional filter in the provider-specific format).

• IdCollection: Array<String> (optional collection of range IDs).

• IsIPBlock: Boolean (when set to true, only IP blocks are returned.

IPRanges: Array<IPRange> Yes

Page 8: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

8

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Definition Parameters The input and output of vRealize Orchestrator workflows are passed as vRealize Orchestrator basic types and composite types. The IPAM provider can choose to extend the composite types that are returned by vRealize Orchestrator workflows. The IPAM service reads IPAM-specific properties of composite types and return them as IPAM service domain object extension data.

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

VRAEndpoint URL String Yes vRealize Automation URL.

VRAEndpoint Username String Yes vRealize Automation user name.

VRAEndpoint Password Secure String

Yes vRealize Automation password.

Endpoint Id String Yes vRealize Automation specific provider endpoint ID.

Endpoint URL String Yes Provider endpoint URL.

Endpoint Username String Yes Provider endpoint user name.

Endpoint Password Secure String

Yes Provider endpoint password.

Endpoint Properties Properties No Provider endpoint properties. This can be an empty array.

AddressSpace Id String Yes Provider-specific address space ID.

AddressSpace Name String Yes Address space name.

AddressSpace Description String No Address space description.

AddressSpace IsDefault Boolean No Specifies whether this is the default address space.

AddressSpace ExtensionData Properties No Prover-specific address space output.

AddressSpace TotalCount Number No Total count of address spaces that match the query. This is needed for paging.

Page 9: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

9

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

IPRange Id String Yes

Provider-specific ID. This ID must be unique within the provider. If the provider does not have IDs, the workflow can generate an ID using a combination of range start address, end address, and address space.

The IPAM service sends the ID to the Allocate workflow, which uses it to uniquely identify the range in the provider endpoint.

IPRange Name String Yes Range name.

IPRange Description String No Range description.

IPRange Start String Yes Range start IP address.

IPRange End String Yes Range end IP address.

IPRange IPVersion String Yes Range type: IPv4 or IPv6.

IPRange AddressSpaceId String No Address space that the range belongs to.

IPRange SubnetPrefixLength Number Yes Range subnet prefix.

IPRange Gateway String No Range gateway.

IPRange PrimaryDNS String No Primary DNS associated with the range.

IPRange SecondaryDNS String No Secondary DNS associated with the range.

IPRange PrimaryWINS String No Primary WINS associated with the range.

IPRange SecondaryWINS String No Secondary WINS associated with the range.

IPRange DNSSuffix String No DNS suffix associated with the range.

IPRange DNSSearchSuffixes String No DNS search suffixes associated with the range

IPRange ExtensionData Properties No Provider-specific range properties.

IPRange TotalCount Number No Total count of IP ranges that match the query. You can use this for paging.

Page 10: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

10

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

CreateIPRangeRequest Id String Yes

Create an IP range by specifying the ID of CreateIPRangeRequest.

This ID is set by the IPAM service to match CreateIPRangeRequest with the corresponding CreateIPRangeResult value.

CreateIPRangeRequest IPBlockIds Array <String>

No

IP block IDs. This ID is unique within provider endpoint.

For example, the IP block is a network container in Infoblox NIOS.

If Start and End are not specified, the next available range is allocated within the IP block.

Either IPBlockIds or Start and End is required. If Start and End are specified, there can only be one matching IP block.

CreateIPRangeRequest AddressSpaceId String No

Provider-specific ID of the address space selected on the network profile.

If specified, use this address space to create a new range instead of dynamically selecting one. Useful for API automation.

CreateIPRangeRequest Start String No Range start IP address

CreateIPRangeRequest End String No Range start IP address

Page 11: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

11

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

CreateIPRangeRequest AssignmentType String Yes

Range assignment type: Static or DHCP.

When AssignmentType = Static, the range is used to Allocate.

When AssignmentType = DHCP, the range is used by the NSX Edge to distribute DHCP addresses. In this case, the range is created in the IPAM provider for informational purpose only.

CreateIPRangeRequest ExternalNetwork

ProfileId String No

vRealize Automation external network profile id used to create a routed or NAT network profile.

CreateIPRangeRequest IPVersion String Yes Range type: IPv4 or IPv6.

CreateIPRangeRequest SubnetPrefix

Length Number Yes Range subnet prefix.

CreateIPRangeRequest Gateway String No Range gateway.

CreateIPRangeRequest PrimaryDNS String No Primary DNS associated with the range.

CreateIPRangeRequest SecondaryDNS String No Secondary DNS associated with the range.

CreateIPRangeRequest PrimaryWINS String No Primary WINS associated with the range.

CreateIPRangeRequest SecondaryWINS String No Secondary WINS associated with the range.

CreateIPRangeRequest DNSSuffix String No DNS suffix associated with the range.

CreateIPRangeRequest DNSSearchSuffix

DNSSearchSuffixes String No

DNS search suffix associated with the range.

*DNSSearchSuffix is renamed to DNSSearchSuffixes in vRealize Automation 7.3.

Page 12: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

12

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

CreateIPRangeRequest NetworkProfileId String Yes

vRealize Automation network profile ID created for the on-demand network.

vRealize Automation 7.2 supports routed networks for third-party IPAM providers.

vRealize Automation 7.3 also supports NAT networks for third-party IPAM providers.

CreateIPRangeRequest BlueprintRequestId String No vRealize Automation blueprint request ID.

DeleteIPRangeRequest Id String

Delete an IP range by using the ID of the DeleteIPRangeRequest.

This id is set by the IPAM service to match DeleteIPRangeRequest with the corresponding DeleteIPRangeResult.

DeleteIPRangeRequest RangeId String

Delete an IP range by specifying the third-party IPAM provider-specific ID. This ID is unique within the provider endpoint.

CreateIPRangeResult CreateIPRange

RequestId String Yes

ID of the corresponding CreateIPRangeRequest.

CreateIPRangeResult RangeId String Yes

Third-party IPAM provider-specific ID. This ID is unique within provider endpoint.

RangeId must be unique within a provider. It contain the network view and the range information.

CreateIPRangeResult AddressSpaceId String No Address space ID where the new IP range was created. Applies to NAT networks.

CreateIPRangeResult Start String Yes Range start IP address.

CreateIPRangeResult End String Yes Range end IP address.

CreateIPRangeResult Gateway String No Range gateway.

CreateIPRangeResult IPVersion String Yes Range type: IPv4 or IPv6.

CreateIPRangeResult SubnetPrefixLength Number Yes Range subnet prefix.

Page 13: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

13

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

DeleteIPRangeResult DeleteIPRange

RequestId

String Yes ID of the corresponding DeleteIPRangeRequest.

DeleteIPRangeResult Status String Yes Result of the release request, either Success or Failure.

DeleteIPRangeResult ErrorCode String No Error code.

DeleteIPRangeResult ErrorMessage String No Error message.

AllocationRequest Id String Yes

Allocation request ID.

The IPAM service sets this ID to match AllocationRequest with the corresponding AllocationRequest.

AllocationRequest AddressSpaceId String No Provider-specific ID of the address space selected on the network profile.

AllocationRequest IPRangeIds Array <String>

No

Provider-specific IDs of ranges to use to allocate IP addresses. Only one range is used to allocate all IP addresses to avoid DNS and gateway info mismatch. If no ranges are specified, extensible attributes specified as machine custom properties or address space are used to allocate IP addresses. Note: vRealize Automation passes multiple rangeIds in the AllocationRequest. The provider chooses one and returns it as part of AllocationResult.

AllocationRequest NicIndex Number No NIC index of the machine resource.

AllocationRequest Description String No Allocation request description.

AllocationRequest Start String No Start IP address. Use this to allocate a specific IP address.

AllocationRequest Size String No Number of IP addresses to allocate. Use this to allocate more than one IP address.

AllocationRequest NetworkProfileId String Yes vRealize Automation network profile ID.

Page 14: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

14

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

Resource Id String Yes vRealize Automation resource ID.

Resource Name String Yes Resource name.

Resource Description String Yes Resource description.

Resource Type String Yes Resource type.

Resource TenantId String Yes vRealize Automation tenant ID.

Resource TenantName String Yes vRealize Automation tenant name.

Resource Properties Properties No Resource properties. When the resource is a virtual machine, these are machine properties.

AllocationResult AllocationRequestID String Yes ID of the corresponding allocation request.

AllocationResult IPAddress Array <String>

Yes Allocated IP addresses.

AllocationResult RangeId String Yes Provider-specific ID of the range used to allocate IP addresses.

AllocationResult IPVersion String Yes Range type: IPv4 or IPv6.

AllocationResult SubnetPrefixLength Number Yes Range subnet prefix.

AllocationResult Gateway String No Range gateway.

AllocationResult PrimaryDNS String No Primary DNS associated with the range.

AllocationResult SecondaryDNS String No Secondary DNS associated with the range.

AllocationResult PrimaryWINS String No Primary WINS associated with the range.

AllocationResult SecondaryWINS String No Secondary WINS associated with the range.

AllocationResult DNSSuffix String No DNS suffix associated with the range.

AllocationResult DNSSearchSuffixes String No DNS search suffixes associated with the range.

ReleaseRequest Id String Yes Release request ID.

ReleaseRequest IPAddress String Yes IP address to be released.

Page 15: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

15

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

COMPOSITE TYPE PROPERTY VRO TYPE REQUIRED DESCRIPTION

ReleaseRequest RangeId String Yes Provider-specific ID of range used to allocate IP address.

ReleaseRequest NicIndex Number No Machine resource NIC index.

ReleaseRequest Description String No Release request description.

ReleaseRequest NetworkProfileId String No vRealize Automation network profile ID.

ReleaseResult ReleaseRequestId String Yes ID of the corresponding release request.

ReleaseResult Status String Yes Result of the release request, either Success or Failure.

ReleaseResult ErrorCode String No Error code.

ReleaseResult ErrorMessage String No Error message.

PagingAndSorting Skip Number Yes Get resources after skipping the specified number of resources.

PagingAndSorting Top Number Yes Return the specified number of resources.

PagingAndSorting Filter String No Filter resources.

PagingAndSorting OrderBy String No Order resources.

Page 16: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

16

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Register a Third-Party IPAM Endpoint

Implement the Register IPAM Endpoint workflow to register a third-party IPAM provider with vRealize Automation. This workflow calls the vRealize Automation endpoint-configuration-service API to register a new endpoint type in the IPAM category.

The schema of the new IPAM endpoint type must conform to the default supported IPAM endpoint type schema and include key-value pair mapping between the workflow definition name and the workflow implementation ID for IPAM provider implementations of required workflows and actions. You can retrieve the default IPAM endpoint type schema from the vRealize Automation ipam-service.

Each endpoint instance must conform to the endpoint type schema but could potentially override some of the schema defaults, such as workflows IDs.

Note: For more information about the vRealize Automation API services, including the ipam-service and the endpoint-configuration-service, open https://{vra-url}/component-registry/services/docs in your installed vRealize Automation client or see the REST API Reference in the vRealize Automation 7.1 or later Information Center

Note: For updates to a previously registered endpoint type, where the IPAM provider must change any of the workflow implementation IDs, the Register IPAM Endpoint workflow supports updates to existing endpoint types and endpoint instances. When the workflow calls the endpoint-configuration-service API to update existing endpoint type, the existing schema is updated and a new set of default key-value pairs for the workflow implementation id are saved. Information about the vRealize Automation service APIs is available at code.vmware.com.

Procedure – Sample Flow REST API Calls to vRealize Automation

1. Authenticate with vRealize Automation and retrieve an authentication token. Provide the authentication token in the authorization header for all subsequent API calls. For information about obtaining and using an authentication token, see the About HTTP Bearer Tokens topic in the vRealize Automation Programming Guide located at docs.vmware.com and code.vmware.com. Optional but recommended: On vRealize Orchestrator servers that have a vRealize Automation plug-in installed (for example, any embedded vRealize Orchestrator that runs inside the vRealize Automation appliance) you can use VCACCAFE:VCACCAFEHost type to simplify calls to the vRealize Automation REST API. The endpoint registration workflow then prompts you to select an existing vRealize Automation host from the vRealize Orchestrator inventory or else register a new host.

2. Create or update an endpoint category named IPAM. Example 1: PUT https://{vra-url}/endpoint-configuration-service/api/categories/IPAM

Body: { name: IPAM, id: IPAM }

Alternatively, if you are using the VCACCAFE:VCACCAFEHost type to make vRealize Automation API calls, you can use the following example statement instead: Example 2:

Page 17: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

17

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

var restClient =

VCACCAFEHOST.createRestClient("com.vmware.csp.core.endpoint.configuration.ap

i");

// the PUT semantic creates a category if it does not exist or updates if it

does exist

restClient.put("/categories/" + "IPAM",JSON.stringify({ name: IPAM, id: IPAM

}) );

3. Retrieve the default IPAM endpoint schema. Example 1: GET https://{vra-url}/ipam-service/api/data-

service/schema/ipam_endpoint_class_id/default

Alternatively, if you are using the VCACCAFE:VCACCAFEHost type to make vRealize Automation API calls, you can use the following example statement instead: Example 2: var restClient =

VCACCAFEHOST.createRestClient("com.vmware.csp.component.ipam.service.api");

var responseContentEndpointTypeSchema = restClient.get("/data-

service/schema/ipam_endpoint_class_id//default").getBodyAsJson();

4. Create or update an endpoint type in the schema with default values for workflow and action IDs. Example : PUT https://{vra-url}/endpoint-configuration-service/api/types/{typeID}

Body: { endpoint type }

Alternatively, you can use the VCACCAFE:VCACCAFEHost to make API calls.

5. Optional: Create or update endpoint instances of the above type with endpoint extensionData conforming to the endpoint type schema created above. The username, password, credentialName, and customProperties are defined in the schema. You can

use ODATA filtering to filter, sort, and paginate endpoint information. Example – creating an endpoint:

POST https://{vra-url}/endpoint-configuration-service/api/endpoints

Body: { endpoint }

After the new endpoint is registered, you can add IPAM endpoint instances and include them in network profiles. See the following topics in the vRealize Automation 7.3 documentation at docs.vmware.com:

• Create a Third-Party IPAM Provider Endpoint

• Create an External Network Profile by Using a Third-Party IPAM Provider

• Create a Routed or NAT Network Profile by Using a Third-Party IPAM Endpoint

Page 18: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

18

Creating a vRealize Orchestrator Package for a vRealize Automation Third Party IPAM Service Provider

Transaction Support

The Allocate workflow can allocate multiple IP addresses at a time. If the workflow fails and returns an error, it might leave some IP addresses allocated in the external provider that were not assigned to a vRealize Automation resource. To avoid out of sync data, make the Allocate workflow transactional and release all allocated IP addresses if the workflow fails.

The Release workflow can release multiple IP addresses at a time. If the workflow fails and returns an error, it might release some IP addresses while vRealize Automation does not recognize that those addresses have been released. When a machine is deleted in vRealize Automation, vRealize Automation calls for the IP address to be released. If the address has already been released as the result of a failed Release workflow, the delete operation fails. To avoid this scenario, ensure that the Release workflow handles the case where vRealize Automation calls to release IP addresses that were already released.

Gateway Allocation for Routed and NAT Networks

Because gateway is an IP address allocated from the subnet's IP range, vRealize Automation can only

understand the gateway IP after the range is created. The third-party IPAM provider Create IP

Range workflow must allocate an IP address for gateway after creating a routed range and return it as

part of the Create IP Range workflow output. The gateway IP address is assigned to the NSX DLR

edge network interface that serves as the gateway for all machines assigned to a routed or NAT network.

Address Spaces

The IPAM service provides optional Get Address Spaces workflow and action definitions to get defined address spaces within an IPAM provider endpoint. If you implement Get Address Spaces, it is called during network profile authoring for external IPAM providers, and users are able to select an address space for the network profile. If a user selects an address space, the value is passed to Get IP Ranges to filter ranges to a specific address space.

Hidden Objects for Routed and NAT Networks

When vRealize Automation instantiates an on-demand network, it creates a network profile that is used to allocate IP addresses for machines assigned to this instance of the network. The network profile is hidden in vRealize Automation and is not visible on the Network Profiles page or during blueprint authoring. vRealize Automation doesn't collect and store inventory from third-party IPAM providers. The third-party IPAM provider must mark objects that it creates for on-demand networks during Create IP Ranges workflow. The IPAM provider can use a hidden flag to filter hidden objects when returning results for the Get Ranges and Get Address spaces workflows and actions.

Network Scale for Routed and NAT Networks

When using an on-demand network, the IP addresses must be unique within a single address space.

Page 19: vRealize Automation Load Balancing - VMware Automation 7.3 also supports NAT networks for third-party IPAM providers. CreateIPRangeRequest BlueprintRequestId String No vRealize Automation

VMware, Inc. 3401 Hillview Avenue Palo Alto CA 94304 USA Tel 877-486-9273 Fax 650-427-5001 www.vmware.com

Copyright © 2017 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright patents and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

Error Handling

If an external IPAM provider workflow fails, it must return a descriptive error to the vRealize Automation IPAM service. The IPAM service defines a set of error codes for common error conditions.

ERROR CODE SAMPLE ERROR MESSAGE

1001 Error allocating a specific IP address [x.x.x.x] because it is already allocated.

1002 Error allocating or creating a next available range.

1005 Error allocating IP address(es) because the list of available IP ranges is exhausted.

1007 Error allocating an IP address [x.x.x.x] that does not belong to IP range [x.x.x.x-x.x.x.x].

2000-xx Reserved for on-demand IPAM errors.

3000-xx Unreserved and available to the provider, for example to create a message indicating failure to communicate with the provider endpoint from a vRealize Orchestrator plug-in or input validation errors.

Error codes display complex errors from a scripting element that is similar to the following example, rather than by using the Throw Exception call:

throw JSON.stringify({ code: 1001, message: 'Could not allocate IP 10.10.1.3

since network 10.10.1.0 is out of IPs' });

Testing and Additional References

The vRealize Automation IPAM SDK vRO Package includes stub implementation of workflows that are

used to test vRealize Automation and the IPAM plug-in end-to-end use cases. The SDK vRO Package may

be available with this SDK document. You can use the SDK vRO Package as a resource as you create your

own external IPAM solution package or plug-in for a specific external IPAM provider. See your VMware

technical resource for details on how to obtain the SDK vRO Package.