Creating and managing hybrid deployables

You can create hybrid deployables to represent Kubernetes and non-Kubernetes resources, such as containers, virtual machines or cloud services so that the platforms can be managed as Kubernetes resources, such as for constructing or updating applications.

Hybrid deployables (deployables.core.hybridapp.io) are introduced for modeling resources without impacting the Kubernetes system hosting application model. These deployables define templates with the associated Deployer type for cross platform deployments and management. Hybrid deployable resources handle deployable components that run on Kubernetes and non-kubernetes platforms, such as virtual machines, containers, and cloud services.

This hybrid deployable Deployable resource kind also defines how other infrastructure platforms, such as Infrastructure management based virtual machine applications can be integrated with the core IBM Cloud Pak for Multicloud Management application model for lifecycle management.

Create a hybrid deployables
Update a hybrid deployables
Delete a hybrid deployables
View the hybrid deployables definition YAML
Virtual machine hybrid deployables
View an example hybrid deployable

Create a hybrid deployable

Compose the definition YAML content for your hybrid deployable. For more information about the YAML structure, including the required fields, see hybrid deployable definition.
Create the hybrid deployable within IBM Cloud Pak for Multicloud Management.

To create a hybrid deployable, you can use the Kubernetes CLI (kubectl) tool, or REST API:
- To use the Kubernetes CLI tool:
  1. Run the following command to apply your file to an apiserver. Replace filename with the name of your file:
```
kubectl apply -f filename.yaml
```
  2. Verify that your hybrid deployable is created, by running the following command:
```
kubectl get deployables.core.hybridapp.io
```
    Ensure that your new hybrid deployable is listed in the resulting output.
- To use REST API, you need to use the Hybrid deployable POST API.

Updating a deployer

To update a deployer, you can use the Kubernetes command line interface (kubectl) tool, or REST API.

To use the Kubernetes CLI tool, the steps are the same as for creating a hybrid deployable.
To use REST API, you need to use the Hybrid deployable PATCH API.

Deleting a hybrid deployable

To delete a hybrid deployable, you can use the Kubernetes command line interface (kubectl) tool, or REST API.

To use the Kubernetes CLI tool, complete the following steps:
1. Run the following command to delete the hybrid deployable from a target namespace. Replace name and namespace with the name of your hybrid deployable and your target namespace:
```
kubectl delete deployables.core.hybridapp.io <name> -n <namespace>
```
2. Verify that your hybrid deployable resource is deleted by running the following command:
```
kubectl get deployables.core.hybridapp.io <name>
```
To use REST API, you need to use the deployer DELETE API:
- Hybrid deployable APIs.

Hybrid Deployable definition YAML structure

apiVersion: core.hybridapp.io/v1alpha1
kind: Deployable
metadata:
  annotations:
  labels:
  name:
  namespace:
spec:
  hybridtemplates:
    - deployerType:
      template:
        apiVersion:
        kind:
        metadata:
        spec:
  placement:
    deployers:
    - name:
      namespace:
    placementRef:
      name:
  dependencies:
  - name:
    apiVersion:
    kind:

Attribute descriptions

Attribute	Required	Description
`apiVersion`	Y	Set the value to `core.hybridapp.io/v1alpha1`.
`kind`	Y	Set the value to `Deployable` to indicate that the resource is a hybrid deployer.
`metadata.annotations`	N	The annotations for the resource.
`metadata.labels`	N	The labels for the resource.
`metadata.name`	Y	The name for identifying the hybrid deployable.
`metadata.namespace`	Y	The namespace resource to use for the hybrid deployable.
`spec.hybridtemplates`	N	Section that identifies the object, such as a virtual machine, or Kubernetes service, that is represented by the deployable.
`spec.hybridtemplates.deployerType`	N	Identifies the deployer type for the object.
`spec.hybridtemplates.template`	N	Identifies the actual object that is represented by the deployable. Depending on the object represented, the fields that need to be defined can be different. For example, see Virtual machine hybrid deployables. To identify a virtual machine, you need to define the `vmid` and possibly the `cfConnection` values.
`spec.placement`	N	Define where the deployable is to be deployed. Alternatively, you can specify a placement rule for the deployable, which can then define how to deploy the deployable.
`spec.placement.deployers`	N	Identifies the deployers where the hybrid deployable is to be deployed.
`spec.placement.placementRef`	N	Identifies the hybrid placement rule for deploying the hybrid deployable.
`spec.dependencies`	N	Specify dependencies between the deployable and other deployables.

Note: A stats section is generated when the resource is created. This section defines the observed state of the resource.

Placement rules and settings

Hybrid deployables can support including references to hybrid placement rules instead of specifically identfiying a Deployer resource. The referenced hybrid placement rule defines the deployerType and other settings for determining where to place the hybrid deployable. You can also directly define the deployer within the hybrid placement rule by name to indicate where to place the deployable:

The following example shows the parameters to define the deployer by name:

placement:
  deployers:
  - name:
    namespace:

The following example shows the parameters to reference a hybrid placement rule for determing deployments:

placement:
  placementRef:
    name:

If you choose to create an application by assembling resources, a hybrid placement rule is automatically created for deploying the associated hybrid deployables to a managed cluster.

Virtual machine hybrid deployables

The Hybrid Application Model supports creating applications that include hybrid deployable resources that represent virtual machines that run on Infrastructure management. Only virtual machines that are provisioned with Infrastructure management can be represented as a hybrid deployable.

Before you can create a hybrid deployable to represent a virtual machine, you need to complete the following tasks:

Install and set up a connection with Infrastructure management. For more information about installing the Infrastructure management, see:
- Installing the IBM Cloud Pak for Multicloud Management
After the connection with Infrastructure management is set up, you need to use Infrastructure management to provision the VM that you want to use in an application. The connection ensures that any VM that is provision with Infrastructure management is automatically discovered and can be searched for and used with the Hybrid Application Model. For more information, see Provisioning Virtual Machines and Instances.
After you provision the VM, you need to record identifying information about the VM so that you can identify the VM when your are creating the hybrid deployable. To define the YAML for the VM hybrid deployable, you need the vmid value to identify the VM. Depending on how your connection to Infrastructure management is set up, you might also need the cfConnection value.

The vmid is the ID that assigned to the VM when it is provisioned with Infrastructure management. The vmid value can be determined by referencing the virtual machine entry that is listed in the console Infrastructure management (Automate infrastructure > Infrastructure management) All VMs & Instances page (Services > Workload > VMs & Templates) or All VMs page (Compute > Infrastructure > Virtual Machines > VMs). You can also determine the vmid from the virtual machine name. The name uses the format cmfid-<vmid>. Record the value for the vmid portion of the name.

The cfConnection specifies the name of the Connection resource that contains the Infrastructure management endpoint and credentials. If the parameter is not specified in the resource YAML for the VM, the default Connection for Infrastructure management, imconnection, is used. If your connection is not using the default Infrastructure management connection, imconnection, you also need to define the cfConnection value.

Note: If you plan to assemble an application that includes a VM hybrid deployable with the console, you do not need to directly create the hybrid deployable resource. You can directly select a VM to assemble into an application. If the hybrid deployable (Deployable) or VM (VirtualMachine) CR does not exist for your selected VM, the resource is created as part of the application assembly process.

Optional. Create the VirtualMachine custom resources (CR) record for the VM. This resource is needed for defining the virtual machine as a resource which can then be represented as a hybrid deployable. If you are planning to assemble an application you do not need to create this resource, it can be automatically created. For more information about creating a VirtualMachine resource, see Virtual machine controller.

The following YAML is an example of a VirtualMachine resource, which uses the default imconnection connection:
```
apiVersion: infra.management.ibm.com/v1alpha1
kind: VirtualMachine
metadata:
  name: virtualmachine-default-cfvmid-279
  namespace: "default"
spec:
  cfConnection:
    name: "imconnection"
  vmid: "279"
```

Create the hybrid deployable resource for the VM.

When you are defining your YAML, you need to specify the vmid value. Depending on how your connection to Infrastructure management is set up, you might also need the cfConnection value. The following example uses the default connection.

This resource defines a hybrid deployable named virtualmachine-default-cfvmid-279 within the default namespace. The namespace for the VM hybrid deployable must be the same as the actual VM namespace. Within the resource spec, the virtual machine that is represented by the deployable is identified. The deployerType indicates that the VM is from Infrastructure management and has the vmid of 279

apiVersion: core.hybridapp.io/v1alpha1
kind: Deployable
metadata:
 name: virtualmachine-default-cfvmid-279
  namespace: default
spec:
  hybridtemplates:
    - deployerType: ibminfra
      template:
        apiVersion: infra.management.ibm.com/v1alpha1
        kind: VirtualMachine
        spec:
          cfConnection:
            name: ''
          vmid: '279'
  placement:
    deployers:
      - name: ibminfra
        namespace: management-infrastructure-management

The referenced deployerType (ibminfra) is the default Deployer resource that is created for Infrastructure management when you install Infrastructure management.

After you use your YAML file with the console or CLI to create the deployable, the vmid is used to populate the details for the VM. The resulting YAML for the created resource can resemble the following file:

apiVersion: core.hybridapp.io/v1alpha1
kind: Deployable
metadata:
   name: virtualmachine-default-cfvmid-279
  namespace: default
spec:
  hybridtemplates:
    - deployerType: ibminfra
      template:
        apiVersion: infra.management.ibm.com/v1alpha1
        kind: VirtualMachine
        metadata:
          finalizers:
            - virtualmachine.infra.management.ibm.com
          name: cfvmid-279
          namespace: default
        spec:
          cfConnection:
            name: ''
          vmid: '279'
  placement:
    deployers:
      - name: ibminfra
        namespace: management-infrastructure-management
status:
  perDeployerStatus:
    management-infrastructure-management/ibminfra:
      phase: ''

Dependencies

A hybrid deployable can have a dependency on another hybrid deployable or on anything else, including a Kubernetes resource.

Within a hybrid deployable, the spec.dependencies section identifies the required resources for that deployable.

For dependencies on other hybrid deployables, the required output for the other deployable can be retrieved from the status (status.perDeployerStatus.outputs) of that hybrid deployable rather than the deployable itself.
For other dependencies the source is distributed with the hybrid deployable. If the dependency, or the status.perDeployerStatus.output of a hybrid deployable dependency, is a Deployable resource, the spec.template for that deployable is created rather than the deployable itself.

The hybrid deployable status aggregates the status of all deployed dependency resources as well as the object references to all output resources. If the output is in a managed cluster, the output is aggregated back to the cluster namespace on the hub cluster as a Deployable resource and the object reference points to that deployable.

As an example. an application can includes two hybrid deployables that are not deployed together:

A Db2 hybrid deployable, which represents a database that is deployed as a virtual machine by using Infrastructure management. This hybrid deployable generates an environment variable within a db2-config ConfigMap, which is required by the second hybrid deployable, Webserver.
A Webserver hybrid deployable, which represents a web server that is deployed as a Deployment by Kubernetes. This Deployment requires the environment variable from the db2-config ConfigMap.

To handle this dependency the following process occurs:

The db2 hybrid deployable (Deployable) is created and the associated virtual machine resource is generated on the Hub cluster.
The Webserver hybrid deployable is created and the associated Deployment and Pod are then created on the managed cluster. However, the Deployment and Pod are in the Error status as it is waiting on the Db2 ConfigMap to be generated.
The ConfigMap is created within the Infrastructure management namespace, such as by Ansible or Service management.

With the ConfigMap created, the Db2 hybrid deployable status is updated to include the ConfigMap. The ConfigMap is also propagated to the managed cluster where the Webserver Deployment and Pod is deployed. With the ConfigMap available, the Pod can run and the Pod status is now changed to Running.

Example hybrid deployable

Kubernetes Service hybrid deployable

apiVersion: core.hybridapp.io/v1alpha1
kind: Deployable
metadata:
  labels:
    ham-sample-app: guestbook
  name: service-guestbook-redis-master-1
  namespace: default
spec:
  hybridtemplates:
    - deployerType: kubernetes
      template:
        apiVersion: v1
        kind: Service
        metadata:
          labels:
            app: redis
            role: master
            tier: backend
          name: redis-master
        spec:
          ports:
            - port: 6379
              targetPort: 6379
          selector:
            app: redis
            role: master
            tier: backend
          type: ClusterIP
  placement:
    placementRef:
      name: ham-sample-guestbook-1
status: {}