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.
- 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.
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.
- 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.
- 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
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
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
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.
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 | READ1 |
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 |
1 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.