Template and template instance APIs

This section includes template and template instance APIs with examples.

POST to create a template from a file
POST to create a template from a source
Create duplicate template
GET the list of templates
GET a specific template
POST to deploy a template
GET the list of deployed templates
Update state of template instance
Modify a template instance
Apply the changes to a template instance
Destroy a template instance
Delete a template instance (stack) after destroying it
Restart OS
Import VM by IDs
Import VM by Name
Create snapshots
Revert to snapshot
Delete a snapshot
Revert to current snapshot
Get snapshots
Taint a resource from a stack
Untaint a resource from a stack
Retrieve and change power states for resources
Start a virtual machine
Stop a virtual machine
Reset virtual machine
Get the status of a stopping or starting a virtual machine
Retrieve stack information

POST to create a template from a file

curl -k -X POST -H "Authorization: BeAfter this the PLAN job should have been started, and they can monitor as usual via the retreive API.arer ${CAM_BEARER_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d @template_create.json "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/templates?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

template_create.json:
{
    "name": "mytemplate",
    "description": "here is the description",
    "type": "userCreated",
    "manifest": {
        "template_type": "Terraform",
        "template": {
            "templateData": "variable \"region\" {\n   default = \"us-east-1\"\n}\n",
            "templateOutput": "",
            "templateVariables": {
                "template_input_params": [
                    {
                        "name": "region",
                        "description": "variable description",
                        "default": "us-east-1",
                        "type": "string",
                        "required": true,
                        "secured": false,
                        "label": "region",
                        "hidden": false,
                        "immutable": false
                    }
                ]
            }
        },
        "template_provider": "IBM"
    },
    "metadata": {
        "displayName": "the template display name"
    }
}

The cloudOE_spaceGuid query parameter governs the namespace to be used when a template is created. In this example, the template gets created in the namespace that $ICP_NAMESPACE resolves to. Now, if you want to create the template to be globally available and not tied to any specific namespace, then omit the cloudOE_spaceGuid query parameter.

Example output:

{
    "description": "here is the description",
    "name": "mytemplate",
    "type": "userCreated",
    "manifest": {
        "template_type": "Terraform",
        "template_provider": "IBM",
        "template": {
            "templateData": "variable \"region\" {\n   default = \"us-east-1\"\n}\n",
            "templateVariables": {
                "template_input_params": [
                    {
                        "name": "region",
                        "description": "variable description",
                        "default": "us-east-1",
                        "type": "string",
                        "required": true,
                        "secured": false,
                        "label": "region",
                        "hidden": false,
                        "immutable": false
                    }
                ]
            }
        }
    },
    "metadata": {
        "displayName": "the template display name"
    },
    "created_at": "2018-01-09T05:10:48.523Z",
    "id": "5a544ed88bec4000200dc328",
    "tenantId": "cd3ed377-8167-4078-b486-309b1f237928",
    "default_template_version": "5a544ed88bec4000200dc329",
    "template_version": {
        "id": "5a544ed88bec4000200dc329",
        "name": "v1.0.0",
        "enabled": true
    },
    "template_versions": [
        {
            "id": "5a544ed88bec4000200dc329",
            "name": "v1.0.0",
            "enabled": true
        }
    ]
}

POST to create a template from a source

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d @template_input.json "https://${CAM_HOST}:30000/cam/api/v1/templates/createFromSource?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

template_input.json:
{
    "template_type": "Terraform",
    "template_format": "HCL",
    "template_source": {
        "github": {
            "url": "https://github.ibm.com/Orpheus/provider-terraform-base",
            "token": "access token for github repository",
            "dir": "subdir/testTemplate",
            "ref": "master"
        }
    }
}

Example output:

{
    "description": "Template contents are hosted in a git repository.",
    "name": "New template hosted in git 129c26100b5b9fe7",
    "type": "userCreated",
    "manifest": {
        "template_type": "Terraform",
        "template_source": {
            "github": {
                "url": "https://github.ibm.com/Orpheus/provider-terraform-base",
                "token": "1234567890",
                "dir": "subdir/testTemplate1",
                "ref": "master"
            },
            "displayUrl": "https://github.ibm.com/Orpheus/provider-terraform-base/tree/master/subdir/testTemplate1",
            "displayUrlReplaceRef": "https://github.ibm.com/Orpheus/provider-terraform-base/tree/REPLACE_REF/subdir/testTemplate1"
        },
        "template": {
            "templateVariables": {}
        }
    },
    "metadata": {
        "displayName": "",
        "longDescription": ""
    },
    "created_at": "2018-01-09T05:24:30.288Z",
    "id": "5a54520e8bec4000200dc32a",
    "tenantId": "cd3ed377-8167-4078-b486-309b1f237928",
    "default_template_version": "5a54520e8bec4000200dc32b",
    "template_version": {
        "id": "5a54520e8bec4000200dc32b",
        "ref": "master",
        "name": "master",
        "enabled": true,
        "displayUrl": "https://github.ibm.com/Orpheus/provider-terraform-base/tree/master/subdir/testTemplate1"
    },
    "template_versions": [
        {
            "id": "5a54520e8bec4000200dc32b",
            "ref": "master",
            "name": "master",
            "enabled": true,
            "displayUrl": "https://github.ibm.com/Orpheus/provider-terraform-base/tree/master/subdir/testTemplate1"
        }
    ]
}

Create duplicate template

This API creates a duplicate of the template along with all versions.

https://{{CAM_HOST}}/cam/api/v1/templates/<templateID>/duplicate?tenantId={{CAM_TENANT_ID}}&ace_orgGuid={{CAM_TEAM_ID}}&cloudOE_spaceGuid=${ICP_NAMESPACE}

The cloudOE_spaceGuid query parameter governs the namespace to be used when the duplicate template is created. In this example, the template gets created in the namespace that $ICP_NAMESPACE resolves to. Now, if you want to create the template to be globally available and not tied to any specific namespace, then omit the cloudOE_spaceGuid query parameter.

Example request body:

{
 "name": "mynewname"
}

GET the list of templates

curl -k -X GET -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/templates?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

The cloudOE_spaceGuid query parameter is optional and the search results display all templates that are created for the namespace $ICP_NAMESPACE. The result also includes all the templates that are globally available.

Example output:

[
    {
        "description": "Kubernetes - An orchestration system for containerized applications, e.g., Nginx.",
        "name": "Kubernetes Cluster with Nginx Deployment",
        "type": "prebuilt",
        "manifest": {
            "template_type": "Terraform",
            "template_format": "HCL",
            "template_provider": "VMware vSphere"
        },
        "metadata": {
            "displayName": "Kubernetes Cluster with Nginx Deployment",
            "longDescription": "Deploys a Kubernetes Cluster in VMware, where Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. This deployment also deploys the NGINX sample application to validate the deployment is operational, where NGINX is an open source web server and load balancer for high-traffic sites.",
            "bullets": [
                {
                    "title": "Clouds",
                    "description": "VMware"
.
.
        "created_at": "2017-10-27T19:17:59.874Z",
        "id": "59f38667d1b007002263c581",
        "tenantId": "DEFAULT",
        "default_template_version": "59f38667d1b007002263c582"
    },

GET a specific template (filter)

curl -k -X GET -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/templates?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&filter=%7B%22where%22%3A%20%7B%22name%22%3A%20%22SingleVirtualMachine%22%20%7D%7D"

Example output:

[
    {
        "description": "Create Virtual Machine with single vnic",
        "name": "SingleVirtualMachine",
        "type": "prebuilt",
        "manifest": {
            "template_type": "Terraform",
            "template_format": "HCL",
            "template_provider": "VMware vSphere"
        },
        "metadata": {
            "displayName": "SingleVirtualMachine",
            "longDescription": "Create Virtual Machine with single vnic on a network label by cloning"
        },
        "created_at": "2017-11-03T15:19:30.566Z",
        "id": "59fc89024722a1001ff2974c",
        "tenantId": "DEFAULT",
        "default_template_version": "59fc89024722a1001ff2974d"
    }
]

POST to deploy a template (stack)

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d @template_input.json "https://${CAM_HOST}:30000/cam/api/v1/stacks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example output:

template_input.json:
{
  "name": "vSphere95",
  "cloud_connection_ids": [
    "5a00ab148af3f3002010ab45"
  ],
  "parameters": [
    {
      "name": "datacenter",      
      "value": "Rack-8283_1000167"
    },
    {
      ....
    },
  ]
  "templateId": "5a00a2448af3f3002010aae1",
  "catalogName": "SingleVirtualMachine",
  "catalogType": "userCreated",
  "forceCreate": "true"
  }

When the template to be deployed has input_datatypes, then use the following information:

Pass the input dataobjects that you want to use as your input to a stack by using the name and Data Type. It uniquely identifies the dataobject instance you want to use. For example:

"input_dataobjects": [
    {
      "name": "DefaultNoBastionHostRequired",
      "datatype": "bastionhost"
    }
  ],

Where:

bastionhost is the Data Type name. It matches the datatype in the input_datatypes of the template you are deploying.
name is the name of the Data Object instance you want to use when you deploy this instance.

For each input_datatype, the template requires an input_dataobject.

In this example, the template requires an input_datatype of "bastionhost". When you deploy a stack from this template, provide the dataobject to use that implements the "bastionhost" datatype:

"input_dataobjects": [
    {
      "name": "DefaultNoBastionHostRequired",
      "datatype": "bastionhost"
    }
  ],

Example Response:


{
  "name": "vSphere95",
  "created_at": "2017-11-06T20:18:11.697Z",
  "templateId": "5a00a2448af3f3002010aae1",
  "namespaceId": "default",
  "templateName": "SingleVirtualMachine",
  "templateCategory": "prebuilt",
  "templateProvider": "VMware vSphere",
  "template_type": "Terraform",
  "template_format": "HCL",
  "applied_state_id": "5a00c3838af3f3002010ab53",
  "latest_state_id": "5a00c3838af3f3002010ab53",
  "cloud_connection_ids": [
    "5a00ab148af3f3002010ab45"
  ],
  "id": "5a00c3838af3f3002010ab53",
  "tenantId": "df87bf8a-2ea9-478d-9b37-2b36da4af6ed",
  "status": "IN_PROGRESS",
  "message": "",
  "action": "CREATE",
  "stack_id": "9cb55c20-c32f-11e7-8d7f-d1b85b52d79c",
  "applied_status": "IN_PROGRESS",
  "applied_action": "CREATE",
  "data": {
    "stack_id": "9cb55c20-c32f-11e7-8d7f-d1b85b52d79c",
    "stack_job_id": "5a00c3838af3f3002010ab53",
    "stack_job_is_latest": true,
    "action": "CREATE",
    "status": "IN_PROGRESS",
    "tenantId": "df87bf8a-2ea9-478d-9b37-2b36da4af6ed"
  }
}

Create a stack (advanced scenario)

Use this procedure if you want to do a plan on the stack before you deploy:

Create the stack entry in the db (this will not deploy anything):

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d @stack_create_input.json "https://${CAM_HOST}:30000/cam/api/v1/stacks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${NAMESPACE}"

Note that for the NAMESPACE must be the desired namespace to deploy to. You need to update this everywhere in the stack deploy APIs.

Example stack_create_input.json:

   {
     "name": "test stack 1",
     "description": "test run plan before deploy",
     "templateId": "5c9bb44b0700a40017b2fa62",
     "cloud_connection_ids": ["5c9a40515edcc0001890e706"]
    }

Example response:

   {
     "name": "test stack 1",
     "description": "test run plan before deploy",
     "created_at": "2019-03-29T14:11:56.495Z",
     "templateId": "5c9bb44b0700a40017b2fa62",
     "namespaceId": "cert-manager",
     "cloud_connection_ids": [
        "5c9a40515edcc0001890e706"
      ],
     "id": "5c9e27ac0700a40017b2fa67",
     "tenantId": "a480bc01-f9c1-4e59-9cd6-1ed7e51703bd"    
     }

Run the job (in this case a plan) on the stack.

Note down the id from the response of step 1 and use this in this POST method. The following example assumes that the id is set as STACK_ID:

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d @stack_plan_input.json "https://${CAM_HOST}:30000/cam/api/v1/stacks/${STACK_ID}?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${NAMESPACE}"

Example stack_plan_input.json:

   {
    "parameters": [
     {
       "name": "testinput1",
       "value": "abc123"
      },
    {
      "name": "testinput2",
      "value": "defg"
    }
     ]
     }

After this start the PLAN job and monitor it by using the retreive API.

GET the list of deployed templates (stacks)

curl -k -X GET -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" "https://${CAM_HOST}:30000/cam/api/v1/stacks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example output:

[
  {
        "name": "My WAS Liberty",
        "created_at": "2017-10-29T16:03:20.985Z",
        "templateId": "59f38692d1b007002263c5e3",
        "namespaceId": "default",
        "templateName": "IBM WebSphere Application Server Liberty V17 on a single virtual machine - VMware vSphere",
        "templateCategory": "chefcontent",
        "templateProvider": "VMware vSphere",
        "template_type": "Terraform",
        "template_format": "HCL",
        "applied_state_id": "59f5fbc9d1b007002263c5fa",
        "latest_state_id": "59f5fbc9d1b007002263c5fa",
        "cloud_connection_ids": [
            "59f3b11bd1b007002263c5f3"
        ],
        "id": "59f5fbc8d1b007002263c5f9",
        "tenantId": "5c0e0a5e-d431-468c-9a11-a3df3978e424",
        "status": "SUCCESS",
        "message": "",
        "action": "CREATE",
        "stack_id": "afa51b40-bcc2-11e7-bbfe-b56e007b5b00",
        "applied_status": "SUCCESS",
        "applied_action": "CREATE",
        "applied_output_namespace": "content_template_output"
    }
]

The cloudOE_spaceGuid query parameter is optional and the search results display all template instances that $ICP_NAMESPACE resolves to.

Update state of template instance

To update the state of the template instance (all the way through terraform), run this command to refresh the "destroying" or "deploying" states. You can run this command until the template instance state moves to successful or failed.

Example:

export CAM_TEMPLATE_ID=5a00c3838af3f3002010ab53
curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:30000/cam/api/v1/stacks/${CAM_TEMPLATE_ID}/retrieve?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response:

{
  "name": "vSphere95",
  "created_at": "2017-11-06T20:18:11.697Z",
  "templateId": "5a00a2448af3f3002010aae1",
  "namespaceId": "default",
  "templateName": "SingleVirtualMachine",
  "templateCategory": "prebuilt",
  "templateProvider": "VMware vSphere",
  "template_type": "Terraform",
  "template_format": "HCL",
  "applied_state_id": "5a00c3838af3f3002010ab54",
  "latest_state_id": "5a00c3838af3f3002010ab54",
  "cloud_connection_ids": [
    "5a00ab148af3f3002010ab45"
  ],
  "id": "5a00c3838af3f3002010ab53",
  "tenantId": "df87bf8a-2ea9-478d-9b37-2b36da4af6ed",
  "status": "SUCCESS",
  "message": "",
  "action": "CREATE",
  "stack_id": "9cb55c20-c32f-11e7-8d7f-d1b85b52d79c",
  "applied_status": "SUCCESS",
  "applied_action": "CREATE",
  "data": {
    "stack_id": "9cb55c20-c32f-11e7-8d7f-d1b85b52d79c",
    "stack_job_id": "5a00c3834e13b5001f4aecd1",
    "stack_job_is_latest": true,
    "status": "SUCCESS",
    "action": "CREATE",
    "message": "\nInitializing provider plugins...\nTerraform has been successfully initialized!\n\nYou may now begin working with Terraform. Try running \"terraform plan\" to see\nany changes that are required for your infrastructure. All Terraform commands\nshould now work.\n\nIf you ever set or change modules or backend configuration for Terraform,\nrerun this command to reinitialize your working directory. If you forget, other\ncommands will detect it and remind you to do so if necessary.\ndata.vsphere_datacenter.datacenter: Refreshing state...\nvsphere_virtual_machine.vm_1: Creating...\n  cluster:

Modify a template instance (stack)

 curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d @plan_input.json "https://${CAM_HOST}:30000/cam/api/v1/stacks/${CAM_TEMPLATE_ID}/plan?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

 plan_input.json:
 {
  "templateVersionId": "59fc89024722a1001ff2974d",
  "parameters": [
    {
      "name": "datacenter",
      "value": "Rack-8283_1000167"
    },
    {
      ...
    },

  ]
 }

For the plan request body, the parameters are optional and the execution plan gets created by using the parameter values from the initial deploy.

Example response:

{
    "name":"vSphere95",
    "created_at":"2017-12-13T14:48:22.937Z",
    "templateId":"5a2b00d7b17b800020af2e7c",
    "namespaceId":"default",
    "templateName":"SingleVirtualMachine",
    "templateCategory":"prebuilt",
    "templateProvider":"VMware vSphere",
    "template_type":"Terraform",
    "applied_state_id":"5a313db7b17b800020af300a",
    "latest_state_id":"5a314639b17b800020af3023",
    "cloud_connection_ids":[
        "5a2b0513b17b800020af2f2b"
    ],
    "id":"5a313db6b17b800020af3009",
    "tenantId":"a8fbbe67-1480-49c0-be60-0084b31a0942",
    "status":"IN_PROGRESS",
    "message":"",
    "action":"PLAN",
    "stack_id":"ab100110-e014-11e7-85f3-c3bc8b9fdda1",
    "applied_status":"SUCCESS",
    "applied_action":"CREATE",
    "data":{
        "stack_id":"ab100110-e014-11e7-85f3-c3bc8b9fdda1",
        "stack_job_id":"5a3146396e53230020466164",
        "stack_job_is_latest":true,
        "action":"PLAN",
        "status":"IN_PROGRESS",
        "tenantId":"a8fbbe67-1480-49c0-be60-0084b31a0942"
    }
}

A successful plan has two states, namely SUCCESS AND SUCCESS_WITH_CHANGES:

The SUCCESS indicates that the plan is successful and there will not be any changes to your environment even if you apply the plan.
The SUCCESS_WITH_CHANGES indicates that the plan is successful, but when you apply it, there will be changes to your environment. Go through the logs to understand more about the changes to the environment. For example, a template is defined to create a virtual machine. You make modifications to the template such that it creates a second virtual machine. The resultant SUCCESS_WITH_CHANGES indicates that if you apply the plan, the second virtual machine will get created.

Apply the changes to a template instance (stack)

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:30000/cam/api/v1/stacks/${CAM_TEMPLATE_ID}/apply?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example output:

{
    "name":"vSphere95",
    "created_at":"2017-12-13T14:48:22.937Z",
    "templateId":"5a2b00d7b17b800020af2e7c",
    "namespaceId":"default",
    "templateName":"SingleVirtualMachine",
    "templateCategory":"prebuilt",
    "templateProvider":"VMware vSphere",
    "template_type":"Terraform",
    "applied_state_id":"5a314892b17b800020af3042",
    "latest_state_id":"5a314892b17b800020af3042",
    "cloud_connection_ids":[
        "5a2b0513b17b800020af2f2b"
    ],
    "id":"5a313db6b17b800020af3009",
    "tenantId":"a8fbbe67-1480-49c0-be60-0084b31a0942",
    "status":"IN_PROGRESS",
    "message":"",
    "action":"APPLY",
    "stack_id":"ab100110-e014-11e7-85f3-c3bc8b9fdda1",
    "applied_status":"IN_PROGRESS",
    "applied_action":"APPLY",
    "data":{
        "stack_id":"ab100110-e014-11e7-85f3-c3bc8b9fdda1",
        "stack_job_id":"5a3148926e53230020466174",
        "stack_job_is_latest":true,
        "action":"APPLY",
        "status":"IN_PROGRESS",
        "tenantId":"a8fbbe67-1480-49c0-be60-0084b31a0942"
    }
}

Destroy a template instance (stack)

 curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:30000/cam/api/v1/stacks/${CAM_TEMPLATE_ID}/delete?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response:

  {
  "name": "vSphere95",
  "created_at": "2017-11-06T20:18:11.697Z",
  "templateId": "5a00a2448af3f3002010aae1",
  "namespaceId": "default",
  "templateName": "SingleVirtualMachine",
  "templateCategory": "prebuilt",
  "templateProvider": "VMware vSphere",
  "template_type": "Terraform",
  "template_format": "HCL",
  "applied_state_id": "5a00c4a08af3f3002010ab57",
  "latest_state_id": "5a00c4a08af3f3002010ab57",
  "cloud_connection_ids": [
    "5a00ab148af3f3002010ab45"
  ],
  "id": "5a00c3838af3f3002010ab53",
  "tenantId": "df87bf8a-2ea9-478d-9b37-2b36da4af6ed",
  "status": "SUCCESS",
  "message": "",
  "action": "DELETE",
  "stack_id": "9cb55c20-c32f-11e7-8d7f-d1b85b52d79c",
  "applied_status": "SUCCESS",
  "applied_action": "DELETE",
  "data": {
    "stack_id": "9cb55c20-c32f-11e7-8d7f-d1b85b52d79c",
    "stack_job_id": "5a00c4a04e13b5001f4aecd2",
    "stack_job_is_latest": true,
    "status": "SUCCESS",
    "action": "DELETE",
    "message": "\nInitializing provider plugins...\nTerraform has been successfully initialized!\n\nYou may now begin working with Terraform.

Delete a template instance (stack) after destroying it

curl -k -X DELETE -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:30000/cam/api/v1/stacks/${CAM_TEMPLATE_ID}?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response: {"count":1}

Restart OS

The API call restarts the OS. It is available only for VMware vSphere virtual machine actions. The option is enabled only when the virtual machine powerstate is ON.

Note: The Virtual Machineresource.id can be retrieved from the update the state of the template instance API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"restart"}' "https://${CAM_HOST}:30000/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

POST method.

Body:{ "task_name: "restart" }

Example response:

{
  "cloud_resource_id": "421ac557-7793-fdd5-7b83-c3525571abfe",
  "task_name": "restart",
  "status": "IN_PROGRESS",
  "created": "2017-11-13T16:47:58.298Z",
  "updated": "2017-11-13T16:47:58.298Z",
  "stack_id": "7d55d130-c239-11e7-b95f-c5cc4d245984",
  "resource_id": "59ff272d4ba47e0020cb6583",
  "resource_name": "vsphere_virtual_machine.vm_1",
  "id": "5a09ccbe9fe5890020316467"
}

Import VM by IDs

Imports an existing virtual machine by using the ID. You can view stack instance in the template deployed instances page.

https://cam-host:<cam_port>/cam/api/v1/stacks/import?tenantId=<cam_tenant_id>&cloudOE_spaceGuid=<cam-space-id>

POST method

For example, import a virtual machine's resources that are available in stack "fit-vm17-76":

Body
{
  "name": "fit-vm17-76",
  "cloudConnectionId": "5a8983938f22883ee775"
  "templateId": "5b39493e3984938943eb8b6",
  "templateVersionId: "5b39493e3984938943eb8c5",
  "idFromProvider": "/Rack-8283_1000167/vm/shared/fit-vm17-76"
}

Where,

name is the name of the stack.
cloudConnectionId is the ID of the connection where the virtual machine can be found. Use the credentials used in that cloud to find the virtual machine.
templateId is to associate a template to a stack instance server.
templateVersionId is the version of the template. It is an optional parameter.
idFromProvider is the id of the virtual machine. The format differs for PowerVC and Openstack.
resourceName is an optional parameter. If resourceName is set, then you can import from providers other than vSphere and OpenStack. If you do not use this parameter, then the default values are as follows:
- openstack_compute_instance_v2.vm_1 for OpenStack instances
- vsphere_virtual_machine.vm_1 for VMWare vSphere instances

Import VM by Name

Imports an existing virtual machine by using the name. You can view the stack instance in the template deployed instances page.

https://cam-host:<cam_port>/cam/api/v1/stacks/import?tenantId=<cam_tenant_id>&cloudOE_spaceGuid=<cam-space-id>

POST method

For example, import a virtual machine resources from stack "fit-vm17-76":

Body
{
  "name": "fit-vm17-76",
  "cloudConnectionName": "fit3",
  "templateName": "Import existing VM with a single disk - VMware vSphere",
  "templateVersionName": "1.0",
  "idFromProvider": "/Rack-8283_1000167/vm/Shared/fit-vm17-76"
}

Where,

name is the name of the stack.
CloudConnectionName is the connection name where the virtual machine can be found. Use the credentials used in that cloud to find the virtual machine.
templateName is to associate a template to a stack instance server. It can be VMware vSphere or PowerVC/OpenStack.
templateVersionName is the version of the template. It is an optional parameter.
idFromProvider is the id of the virtual machine. The format differs for PowerVC and Openstack.
resourceName is an optional parameter. If resourceName is set, then you can import from providers other than vSphere and OpenStack. If you do not use this parameter, then the default values are as follows:
- openstack_compute_instance_v2.vm_1 for OpenStack instances
- vsphere_virtual_machine.vm_1 for VMWare vSphere instances

Create snapshot

This API creates a virtual machine snapshot for a VMware instance.

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

Sample URL:

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"snapshot", "parameters": [ \
   { \
       "name": "snapshot_name", \
       "value": ${SNAPSHOT_NAME} \
   }, \
   { \
       "name": "quiesce", \
       "value": true || false \
   }, \
   { \
       "name": "memory", \
       "value": true || false \
   }, \
   { \
       "name": "description", \
       "value":${DESCRIPTION} # Optional \
   } \
   ]}' "https://${CAM_HOST}:30000/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

POST method

BODY:

{
  "task_name": "snapshot",
  "parameters": [
    {
       "name": "snapshot_name",
       "value": "NAME"
    },
    {
       "name": "quiesce",
       "value": false
    },
    {
       "name": "memory",
       "value": false
    },
    {
       "name": "description",
       "value": "DESCRIPTION"
    }
   ]
  }

Note:

The long ID in the URL after iaasResources is the RESOURCE_ID or the ID of the virtual machine.
The description is an optional parameter.

Revert to a snapshot

This API reverts to the selected snapshot.

Note:

The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.
The snapshot_id can be retrieved from the Get snapshots API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"revertToSnapshot", "parameters": [ \
   { \
       "name": "snapshot_id", \
       "value": ${SNAPSHOT_ID} \
   } \
   ]}' "https://${CAM_HOST}:30000/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

POST method

Sample BODY:

{
  "task_name": "revertToSnapshot",
  "parameters": [
    {
      "name": "snapshot_id",
      "value": "snapshot-19477"
    }
   ]
}

Note: The long ID in the URL after iaasResources is the RESOURCE_ID or the ID of the virtual machine.

Delete snapshot

This API deletes the selected snapshot.

Note:

The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.
The snapshot_id can be retrieved from the Get snapshots API.

Sample URL:

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"deleteSnapshot", "parameters": [ \
   { \
       "name": "snapshot_id", \
       "value": ${SNAPSHOT_ID} \
   } \
   ]}' "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

POST method

Sample BODY:

{
  "task_name": "deleteSnapshot",
  "parameters": [
   {
     "name": "snapshot_id", 
     "value": "snapshot-19477"
   }
  ]
 }

Note: The long ID in the URL after iaasResources is the RESOURCE_ID or the ID of the virtual machine.

Revert to current snapshot

This API restores to the parent snapshot of the current state of a virtual machine.

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"revertToCurrent"}' "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Sample URL:

https://cam-proxy:<cam_port>/cam/api/v1/iaasresources/5c47740ef76392001eb4d073/tasks

POST method

BODY:

{
  "task_name": "revertToCurrent"
}

Note: The long ID in the URL after iaasResources is the RESOURCE_ID or the ID of the virtual machine.

Get snapshots

This API retrieves a list of snapshots.

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X GET -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/query/getsnapshots?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Sample URL:

https://cam-proxy:<cam_port>/cam/api/v1/iaasresources/5c47740ef76392001eb4d073/query/getsnapshots

GET method

Note: The long ID in the URL after iaasResources is the RESOURCE_ID or the ID of the virtual machine.

Taint a resource from a stack

Note: The Virutal Machine resource.id can be retrieved from the update the state of the template instance API.

export CAM_RESOURCE_ID=<resource.id>

Note: The resource.id can be retrieved from Update state of template instance POST /stacks/id/retrieve call.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/stacks/${CAM_TEMPLATE_ID}/taint/${CAM_RESOURCE_ID}?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example output:

{
    "name": "vSphere95",
    "created_at": "2018-01-10T18:35:52.140Z",
    "templateId": "5a4fe8f98bec4000200dc310",
    "namespaceId": "default",
    "templateName": "SingleVirtualMachine",
    "templateCategory": "userCreated",
    "templateProvider": "IBM",
    "template_type": "Terraform",
    "applied_state_id": "5a565d4d8bec4000200dc32f",
    "latest_state_id": "5a56600a8bec4000200dc331",
    "cloud_connection_ids": [
        "5a3035908bec4000200dc30d"
    ],
    "id": "5a565d088bec4000200dc32c",
    "tenantId": "cd3ed377-8167-4078-b486-309b1f237928",
    "status": "IN_PROGRESS",
    "message": "",
    "action": "TAINT",
    "stack_id": "1616c4e0-f635-11e7-b2c8-2b0dbae0c060",
    "applied_status": "SUCCESS",
    "applied_action": "APPLY",
    "data": {
        "stack_id": "1616c4e0-f635-11e7-b2c8-2b0dbae0c060",
        "stack_job_id": "5a56600a035d8000204e8f27",
        "stack_job_is_latest": true,
        "action": "TAINT",
        "status": "IN_PROGRESS",
        "tenantId": "cd3ed377-8167-4078-b486-309b1f237928"
    }
}

Untaint a resource from a stack

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:30000/cam/api/v1/stacks/${CAM_TEMPLATE_ID}/untaint/${CAM_RESOURCE_ID}?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example output:

{
    "name": "vSphere95",
    "created_at": "2018-01-10T18:35:52.140Z",
    "templateId": "5a4fe8f98bec4000200dc310",
    "namespaceId": "default",
    "templateName": "SingleVirtualMachine",
    "templateCategory": "userCreated",
    "templateProvider": "IBM",
    "template_type": "Terraform",
    "applied_state_id": "5a565d4d8bec4000200dc32f",
    "latest_state_id": "5a56618b8bec4000200dc332",
    "cloud_connection_ids": [
        "5a3035908bec4000200dc30d"
    ],
    "id": "5a565d088bec4000200dc32c",
    "tenantId": "cd3ed377-8167-4078-b486-309b1f237928",
    "status": "IN_PROGRESS",
    "message": "",
    "action": "UNTAINT",
    "stack_id": "1616c4e0-f635-11e7-b2c8-2b0dbae0c060",
    "applied_status": "SUCCESS",
    "applied_action": "APPLY",
    "data": {
        "stack_id": "1616c4e0-f635-11e7-b2c8-2b0dbae0c060",
        "stack_job_id": "5a56618b035d8000204e8f28",
        "stack_job_is_latest": true,
        "action": "UNTAINT",
        "status": "IN_PROGRESS",
        "tenantId": "cd3ed377-8167-4078-b486-309b1f237928"
    }
}

Retrieve and change power states for resources

This API retrieves and changes power states for resources.

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X GET -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/query/getPowerState?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

GET method

Response: {
"poweredOn": true || false
}

Start a virtual machine

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"start"}' "https://${CAM_HOST}:30000/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response

{
  "cloud_resource_id": "421ac557-7793-fdd5-7b83-c3525571abfe",
  "task_name": "start",
  "status": "IN_PROGRESS",
  "created": "2017-11-13T16:51:37.972Z",
  "updated": "2017-11-13T16:51:37.972Z",
  "stack_id": "7d55d130-c239-11e7-b95f-c5cc4d245984",
  "resource_id": "59ff272d4ba47e0020cb6583",
  "resource_name": "vsphere_virtual_machine.vm_1",
  "id": "5a09cd999fe5890020316468"
}

Stop a virtual machine

export CAM_RESOURCE_ID=<resource.id>

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"stop"}' "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response

{
  "cloud_resource_id": "421ac557-7793-fdd5-7b83-c3525571abfe",
  "task_name": "stop",
  "status": "IN_PROGRESS",
  "created": "2017-11-13T16:47:58.298Z",
  "updated": "2017-11-13T16:47:58.298Z",
  "stack_id": "7d55d130-c239-11e7-b95f-c5cc4d245984",
  "resource_id": "59ff272d4ba47e0020cb6583",
  "resource_name": "vsphere_virtual_machine.vm_1",
  "id": "5a09ccbe9fe5890020316467"
}

Reset a virtual machine

You can reset and restart a VMware virtual machine.

Note: The Virtual Machine resource.id can be retrieved from the update the state of the template instance API.

curl -k -X POST -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"task_name":"reset"}' "https://${CAM_HOST}:<CAM_PORT>/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response

{
  "cloud_resource_id": "421ac557-7793-fdd5-7b83-c3525571abfe",
  "task_name": "reset",
  "status": "IN_PROGRESS",
  "created": "2017-11-13T16:47:58.298Z",
  "updated": "2017-11-13T16:47:58.298Z",
  "stack_id": "7d55d130-c239-11e7-b95f-c5cc4d245984",
  "resource_id": "59ff272d4ba47e0020cb6583",
  "resource_name": "vsphere_virtual_machine.vm_1",
  "id": "5a09ccbe9fe5890020316467"
}

Get the status of a stopping or starting a virtual machine

curl -k -X GET -H "Authorization: Bearer ${CAM_BEARER_TOKEN}" -H "Accept: application/json" -d '{"task_name":"stop"}' "https://${CAM_HOST}:30000/cam/api/v1/iaasresources/${CAM_RESOURCE_ID}/tasks/${CAM_IAASTASK_ID}?tenantId=${CAM_TENANT_ID}&ace_orgGuid=${ICP_TEAM}&cloudOE_spaceGuid=${ICP_NAMESPACE}"

Example response:

{
  "cloud_resource_id": "421ac557-7793-fdd5-7b83-c3525571abfe",
  "task_name": "stop",
  "status": "SUCCESS",
  "created": "2017-11-13T16:47:58.298Z",
  "updated": "2017-11-13T16:48:03.728Z",
  "stack_id": "7d55d130-c239-11e7-b95f-c5cc4d245984",
  "resource_id": "59ff272d4ba47e0020cb6583",
  "resource_name": "vsphere_virtual_machine.vm_1",
  "message": "",
  "id": "5a09ccbe9fe5890020316467"
}

Retrieve stack information

POST to /api/v1/stacks/<stackID>/retrieve

This retrieves information about the stack including its parameters. However, if any of those parameters have secured:true, then the values for those parameters are hidden, that is, replaced with asterix by default.

To return secured values back in plain text, run the POST with showSecured=true parameter.

POST to /api/v1/stacks/<stackID>/retrieve?showSecured=true