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. This makes it possible for consumers to quickly provision and deprovision an environment as needed.

Getting started

The security administrator defines the various roles that are required, such as the domain administrator, network administrator, approvers, and consumers. For more information about setting up security for cloud provisioning, see Preparing to use cloud provisioning in IBM z/OS Management Facility Configuration Guide.

Using the Cloud Provisioning tasks, your system programmers and application programmers can perform the following actions:

System programmers:
- Define the cloud domain (systems), administrators for the domain, and classes of users (tenants) for the domain.
- Prepare software services templates, which are used to provision z/OS® software. Service providers add templates, associate tenants with the templates, create resource pools for the templates, test the templates, then publish them to make them available for consumers.
System programmers or application programmers:
- Provision software from templates, creating software services instances.
- Manage software services instances.

For an illustration of cloud provisioning, see Figure 1.

The network administrator defines the cloud configuration, systems, ports, APPLIDs, and IP address. The security administrator authorizes administrator IDs, provisioning IDs, approval IDs, and consumer IDs. The Landlord creates the doman. The domain administrator creates tenants, and associates templates with tenants and resource pools The consumer runs templates. — Figure 1. Cloud Provisioning Summary

Domains define the scope of cloud provisioning

A cloud provisioning domain 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.

A landlord, typically a z/OS system programmer, decides which system or systems (LPARs) are used for provisioning, creates a domain, and identifies the domain administrator. The domain administrator is typically a middleware system programmer for the middleware that is to be provisioned. For more information about defining the landlord and domain administrator, see Preparing to use cloud provisioning.

To help you get started quickly, a default domain is provided. The default domain is fully operational without any further configuration, and is accessible to any z/OSMF administrator. A default tenant is associated with the default domain.

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
That the instance can be relocated to a system in the domain other than the system it was originally provisioned on. The instance can run on only one system in the sysplex at a time.

Templates guide provisioning

To make an environment available to consumers as a software service, a domain administrator creates and configures a software services template. The template describes what is provisioned. 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 regions.

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

The template might need to be customized for the installation – for example, to conform with naming standards in your company. You might modify variables that are input to the workflow, or use a properties file that is provided with the template to configure the provisioned software. For information about customization, you typically refer to documentation that is included with the template by the software provider. In addition, the domain administrator:

Adds the software services template to a tenant.
Connects the template to network and WLM resource pools, as appropriate. Resource pools are sets of z/OS resources that are required by the z/OS software service, for example, ports, IP addresses, or APPLIDs.

When a template requires resource pools, for example, when you want to dynamically allocate ports to provisioned sofware instances, the network and WLM resource pool administrators (typically z/OS system programmers) use the appropriate z/OSMF tasks to complete the resource pools.

Offering self-service provisioning to a development team might require that some steps in the template, or certain actions, run under automation IDs. Any use of these user IDs in a template must be approved. 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. (The workflow element is runAsUser ID, and the ID is sometimes referred to as a runAsUser ID). Approval records can also be defined for the template in general, and for a domain. Approval records must be approved by the approvers (typically identified by user ID) before the template can be tested or published.

The domain administrator tests the template to ensure that it successfully provisions the software, that is, creates the environment. Software that is provisioned from a template is known as a software services instance. (Note that this is different than a software instance that you manage with the Software Management task. A software instance is a collection of data sets containing installed software, and other data sets that may be associated with that installed software.) You manage a software services instance by using actions such as Remove and deprovision.

Publishing the template makes it available to consumers in the tenant – the application developers who require the new environment.

Summary

The terms that you need to understand for provisioning and managing provisioned software are defined here.

Resources

The following are the key resources in the Cloud Provisioning tasks.

Table 1. Resources for Cloud Provisioning
Resource	Description
Domain	Defines the management scope for tenants, services, and resource pools. A domain consists of one or more z/OS systems. A z/OS system can be in a single domain or in multiple domains that are managed by a single instance of z/OSMF. A cloud domain is defined by a z/OS system programmer who acts as the `landlord`. Each cloud domain is assigned one or more middleware system programmers who act as domain administrators. A base z/OSMF configuration includes one domain by default — the default domain.
Resource pool	Identifies the z/OS resources that are required by a z/OS software service. In a cloud domain with multiple tenants, the resource pool defines the scope of resource sharing and resource isolation. For example, a resource pool can define a range of dedicated IP addresses or ports for each tenant.
Tenant	Defines the group of users who have the authority to provision software instances. A tenant consists of a user or group of users that have contracted for the use of specified services and pooled z/OS resources that are associated with the services in a domain. A base z/OSMF configuration includes one tenant by default — the default tenant.

User roles

The following are the key roles in the Cloud Provisioning tasks.

Table 2. User roles for Cloud Provisioning
Role	Performer	Description
Landlord	z/OS system programmer	Defines the cloud domains and the associated system resources for the cloud. The landlord also designates one or more users as domain administrators.
Domain administrator	Middleware system programmer	Manages a domain. The domain administrator is responsible for defining services, tenants, and resource pools for the domain, and managing the relationship across tenants, services, and resource pools.
Resource pool networking administrator	Network administrator	Manages the resource pool for the networking resources in the cloud, such as network configuration policies.
Resource pool WLM administrator	Performance administrator	Manages the resource pool for the WLM resources in the cloud, such as WLM policies.
Security administrator	Security administrator	Maintains the installation's security manager, such as RACF.
Template approver	System programmer or security administrator	Responsible for approving the pending approval records that are associated with the template.
Consumer	Application programmer	Has access to the software services and resource pools for a tenant. This user can provision a software services instance by using a software services template, and can manage the lifecycle of a software services instance.

Objects

The following are some basic objects that you work with in the Cloud Provisioning tasks.

Table 3. Objects for Cloud Provisioning
Object	Description
Instance, or software services instance	Represents software that is provisioned by using 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.

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 4.

Table 4. 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 Preparing to use cloud provisioning in 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 to exploit cloud provisioning.

Using the Swagger interface

You can use the Swagger interface to display information about the IBM Cloud Provisioning and Management for z/OS REST APIs.

For more information, see Using the Swagger interface.