Obtain an IP address

Use this operation to obtain an IP address from a resource pool that has a configured network resource pool.

HTTP method and URI path

POST /zosmf/resource-mgmt/rest/<version>/rdp/network/ip/obtain

In this request:

<version>: Is the URI path variable that identifies the version of the z/OSMF service. The following value is valid: 1.0.

Query parameters

None.

Description

This operation obtains an IP address from a resource pool with a configured network resource pool.

On successful completion, HTTP status code 200 (OK) is returned, indicating that the request resulted in an IP address being obtained.

Request content

The request content is expected to contain a JSON object that describes the IP address to be obtained. See Table 1.

Table 1. Request content for the obtain IP address request
Field name	Type	Required or optional	Description
template-uuid	String	Required	Unique identifier for the template that is associated with the resource pool. Derived from a workflow internal variable, ${_workflow-templateID}.
template-name	String	Required	Name of the template that is associated with the resource pool. Derived from workflow internal variable, ${_workflow-templateName}.
tenant-id	String	Required	ID of the tenant that is associated with the resource pool. Derived from workflow internal variable, ${_workflow-tenantID}.
network-parms	JSON object	Required	Network. parameters for the request. See Table 2.

Table 2. Network parameters fields
Field	Type	Required or optional	Description
name	String	Optional	Name used in a panel for the Configuration Assistant task. Derived from a workflow internal variable, ${_workflow-softwareServiceInstanceName}.
usage-type	String	Optional	Used as a filter. If not specified, only network resource pools without a usage type match. If specified, must match the usage type in the network resource pool definition in the Configuration Assistant task.
ipaddr	String	Required	IP address. The value can be: A specific IP address Provision that IP address. The IP address must fit within the available IP address allocation range. Available ranges are associated with the targeted network resource pool, and match the provided usage type. any4 Provision any available Ipv4 address, from the available range. any6 Provision any available IPv6 address, from the available range.
system-name	String	See description	Specifies the target system that the resource will be provisioned on. Required if there is more than one system in the network resource pool. Derived from a workflow internal variable, ${_workflow-systemName}.
deployment-id	String	Optional	Workflow-defined string token, used to group all provisioned resources with a server instance.
host-name	String	Optional	Indicates that the domain name server that is configured to the associated IP address allocation range is to be updated with the IP address and the concatenation of the host name and the zone name from the IP address allocation range. Requires a domain name server object to be configured by the network administrator.

Authorization requirements

The user must be a consumer in the tenant, or a network administrator in the domain that the tenant is associated with.

For more information, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 200 (OK) is returned, with a response body. See Response content.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body that provides the reason code that is indicated and associated error message.

Table 3. HTTP error response codes for an obtain IP address request
HTTP error status code	Description
`HTTP 500 Internal server error`	The server encountered an error. See the response body for a JSON object with information about the error.

Response content

On successful completion, the service returns a response body, which contains a JSON object with details about the request. See Table 4.

Table 4. Response from an obtain IP address request
Field	Type	Description
id	String	Identifier of the IP address.
ipaddr	String	IP address returned from the Configuration Assistant task.

Example HTTP interaction

In Figure 1, a request is submitted to obtain an IP address.

Figure 1. Sample request to obtain an IP address, with the request body

POST https://localhost:4444/zosmf/resource-mgmt/rest/1.0/rdp/network/ip/obtain

{
     "template-uuid":"F0F1A1C2",     
     "template-name":"CICSBasic",    
     "tenant-id":"IZU$0AA",         
     "network-parms" :
     {
             "name":"CICSA IP",               
             "usage-type":"internal",         
             "ipaddr":"any4",                     
             "system-name":"SY1",           
             "deployment-id":"CICSBasic",  
             "host-name":"myHostName",  
         }
 }

The following is the response body for the example obtain IP address request.

{
   "id":"101",
   "ipaddr":"192.168.1.1"
 }