Cloud provisioning services

The cloud provisioning services are a set of application programming interfaces (APIs), which are implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to perform software provisioning for IBM Cloud Provisioning and Management for z/OS. This includes creating instances of IBM® middleware, such as IBM Customer Information Control System (CICS®), IBM DB2®, IBM Information Management System (IMS™), IBM MQ, and IBM WebSphere Application Server (WAS), and creating middleware resources, such as MQ queues, CICS regions, and DB2 databases..

To exploit cloud provisioning, users known as service providers make software services available to users known as consumers. Consumers, from a selection of software services, can quickly provision and deprovision software services as needed.

To make software services available to consumers, service providers prepare and publish software services templates. The templates guide the provisioning. For example, a template might request that a DB2 subsystem be deployed onto a z/OS® system with three databases, or might create a set of CICS AORs and TORs.

To provision the middleware, templates start and run z/OSMF workflows. So, a template includes a workflow definition file, along with other files, which might include a file that defines input variables for the workflow, and a file that defines actions that can be used against the provisioned software.

Software that is provisioned from a template is known as a software services instance. (Note that this is different than a software instance, which you manage with the Software Management task.) You manage a software services instance by using actions such as Remove and deprovision.

Software services templates are associated with a domain, which defines a system or set of systems in the sysplex. The systems in the domain must be included in the group of systems named IYUCLOUD in the Systems task of the z/OSMF Settings category.

Owners of computing resources, known as landlords, define the domains and the domain administrators. The domain administrator role overlaps with the service provider role. In fact, the domain administrator might be thought of as a service provider when it is viewed from the standpoint of resource management.

When a domain includes more than one system, the domain administrator can specify:

The systems that are to be used as potential targets for provisioning
How the target system should be selected when the software service is provisioned: either automatically, by z/OSMF, or manually, by the consumer.

The domain administrator makes these selections when adding a template and resource pool to a tenant. Tenants are users or classes of users of the domain.

In addition to defining domains and tenants, resource management includes specifying various administrators. Network and workload administrators are needed when a template requires a resource pool, that is, a set of z/OS resources that are required by the z/OS software service. When service providers associate templates with tenants, they also indicate whether the template requires a resource pool. The network and workload administrators, then, use the appropriate z/OSMF tasks to complete the resource pool.

In summary, to provision and manage provisioned software, you work with:

Domain: Defines the management scope for tenants, services, and resource pools.
A domain consists of a z/OS system or set of systems in the sysplex. There can be up to 36 domains. Domains are defined by landlords. Each cloud domain is assigned one or more domain administrators.
Resource pool: Identifies z/OS resources that are required by a z/OS software service. A resource pool defines the scope of shared z/OS resources within a cloud domain that has multiple tenants.
Tenant: Defines the resource sharing scope, for example, a line of business or a class of users.
A tenant consists of a user or group of users that have contracted for use of specified services, and pooled z/OS resources that are associated with the services in a domain.

Instance, or software services instance: Represents software that has been provisioned, typically through the use of templates.
Template, or software services template: Represents a z/OS middleware or a z/OS middleware resource service. A template consists of workflows and input variables that can be used to provision z/OS software, actions that can be used with the provisioned software (the instance), and documentation.
Approval: Approval records are created for a template when a workflow or action definition file contains an element that identifies a user ID under which a workflow step or action is to be performed (a runAsUser ID). They can also be defined for the template in general, and for a domain. Approval records must be approved by the approvers (identified by user ID) before the template can be test run or published.

The following are the key roles for IBM Cloud Provisioning and Management for z/OS.

Consumer: A user who has access to the software services and resource pools for a tenant. This access is granted when a domain administrator adds the user's ID to a tenant. A consumer can provision a software services instance, using a software services template, and can manage the lifecycle of a software services instance.
Domain administrator: A user who manages a domain. The domain administrator is responsible for defining software services, tenants, and resource pools for the domain, and managing the relationship across tenants, services, and resource pools.
Landlord: A user who defines the domain, domain administrators, and the associated system resources, for the cloud.
Resource pool administrator: A user who is responsible for managing a resource pool.
Service provider: A user who makes software services available to consumers, by preparing and publishing software services templates.

The basic procedure for provisioning software is:

Define domains and tenants. See Resource management services.
Create a template, specifying the workflow, action and variables files that were provided by the software vendor.
The template is added to the software services catalog.
Add the template to a tenant.
Modify the template as needed.
Approve any approval records that were created for runAsUser IDs, for the template in general, and for the domain.
Test the template and ensure that it successfully creates an instance, that is, that it provisions the software and that the actions defined for the instance perform as expected.
Publish the template to make it available to consumers.
Run the template to create a software instance.

Authorization requirements

Use of the cloud provisioning services APIs requires the client to be authenticated. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

In addition, the user’s z/OS user ID may need access to other resources, including those that define roles. The specific requirements for each cloud provisioning service are described in the topic for that service. For a summary of resources related to roles, see Table 1.

Table 1. SAF resources for Cloud Provisioning Roles
Role	Class	Resources	Access
Landlord	ZMFCLOUD	<SAF-prefix>.ZOSMF.PROVISIONING. RESOURCE_MANAGEMENT.saf_cloud_groupID_prefix	READ
Domain administer	ZMFCLOUD	<SAF-prefix>.ZOSMF.PROVISIONING. RESOURCE_MANAGEMENT.domainGroupID	READ
Domain approver	ZMFCLOUD	<SAF-prefix>.ZOSMF.TEMPLATE. APPROVERS.domainGroupID	READ
Template runAsUser ID	ZMFCLOUD	<SAF-prefix>.ZOSMF.TEMPLATE. RUNASUSERS.domainGroupID.templateID	READ¹
Template approver	ZMFCLOUD	<SAF-prefix>.ZOSMF.TEMPLATE. APPROVERS.domainGroupID.templateID	READ
Tenant	ZMFCLOUD	<SAF-prefix>.ZOSMF.PROVISIONING. RESOURCE_MANAGEMENT.tenantGroupID	READ
Resource pool network administrator	ZMFCLOUD	<SAF-prefix>.ZOSMF. RESOURCE_POOL.NETWORK.domainGroupID	READ
Resource pool WLM administrator	ZMFCLOUD	<SAF-prefix>.ZOSMF. RESOURCE_POOL.WLM.domainGroupID	READ

¹ Successful READ attempts for the <SAF-prefix>.ZOSMF.TEMPLATE. RUNASUSERS.domainGroupID.templateID resource are audited. Prior to switching identities to the runAsUser user ID, z/OSMF does an authorization check for access to this resource. If the authorization is successful, the runAsUser ID has access and an audit record is generated. If the authorization check fails, no audit record is generated and switching to the runAsUser user ID does not occur. The workflow fails.

For details about security for the cloud provisioning roles, see IBM z/OS Management Facility Configuration Guide.

For information about how to prepare software for provisioning through the REST APIs or the z/OSMF Cloud Provisioning tasks, including the format of the file for defining actions, see Preparing software for cloud provisioning.