API Endpoints: WSL

Landscape Documentation
1

GET /child-instance-profiles

Gets a list of child instance profiles.

Required parameters:

  • none

Optional parameters:

  • limit: The maximum number of results returned by the method. It defaults to 1000.
  • offset: The offset inside the list of results.

Example request:

curl -X GET https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT"

Example output:

{
    "count": 1,
    "results": [
        {
        "id": 2,
        "name": "stock-ubuntu-2404",
        "title": "Stock Ubuntu 24.04",
        "instance_type": "WSL",
        "description": "The image from the store",
        "image_name": "Ubuntu-24.04",
        "image_source": null,
        "cloud_init_contents": null,
        "cloud_init_secret_name": null,
        "tags": [
            "windows_desktops",
            "windows_laptops"
        ],
        "all_computers": false,
        "access_group": "global",
        "computers": {
          "constrained": [2, 3, 4, 5],
          "non-compliant": [3, 5],
          "pending": [4]
        }
      }
    ],
    "next": null,
    "previous": null
}

POST /child-instance-profiles

Creates a child instance profile.

Required parameters:

  • title: A title for the profile.
  • description: A human readable description for the profile.
  • image_name: The name of the WSL image to use (e.g. Ubuntu-24.04).

Optional parameters:

  • image_source: The URL or file path for the rootfs image.
  • cloud_init_contents: The base64-encoded cloud init file contents.
  • access_group: Optional name of the access group to create the profile under; defaults to Global Access.
  • tags: A comma separated string of tag names to associate with the profile.
  • all_computers: If true, this profile will be associated with all computers; defaults to false.

Example requests:

curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Stock Ubuntu 24.04", "description": "The image from the store", "image_name": "Ubuntu-24.04", "tags": "windows_laptops,windows_desktops"}'

curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d "{\"title\": \"Customized Ubuntu 24.04\", \"description\": \"The image from the store customized\", \"image_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < cloud_init.yaml)\"}"

curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Custom Rootfs Image", "description": "My custom image", "image_name": "CustomUbuntu", "image_source": "https://example.com/myimage.tar.gz"}'

Example output:

{
    "id": 2,
    "name": "customized-ubuntu-2404",
    "title": "Customized Ubuntu 24.04",
    "instance_type": "WSL",
    "description": "The image from the store customized",
    "image_name": "Ubuntu-24.04",
    "image_source": null,
    "cloud_init_contents": "********",
    "cloud_init_secret_name": null,
    "tags": [
        "windows_desktops",
        "windows_laptops"
    ],
    "all_computers": false,
    "access_group": "global",
    "computers": {
      "constrained": [2, 3, 4, 5],
      "non-compliant": [],
      "pending": [2, 3, 4, 5]
    }
}

DELETE /child-instance-profiles/<str:profile_name>

Delete the specified child instance profile.

Required parameters:

  • none

Optional parameters:

  • none

Example request:

curl -X DELETE https://your-landscape.domain.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT"

Example output:

Empty response.

GET /child-instance-profiles/<str:profile_name>

Get details of the specified child instance profile.

Required parameters:

  • none

Optional parameters:

  • none

Example request:

curl -X GET https://your-landscape.domain.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT"

Example output:

{
  "id": 2,
  "name": "stock-ubuntu-2404",
  "title": "Stock Ubuntu 24.04",
  "instance_type": "WSL",
  "description": "The image from the store",
  "image_name": "Ubuntu-24.04",
  "image_source": null,
  "cloud_init_contents": null,
  "cloud_init_secret_name": null,
  "tags": [
    "windows_desktops",
    "windows_laptops"
  ],
  "all_computers": false,
  "access_group": "global",
  "computers": {
    "constrained": [2, 3, 4, 5],
    "non-compliant": [3, 5],
    "pending": [4]
  }
}

PATCH /child-instance-profiles/<str:profile_name>

Edit a child instance profile.

Required parameters:

  • None.

Optional parameters:

  • title: A title for the profile.
  • description: A human readable description for the profile.
  • access_group: Name of the access group for the profile under.
  • tags: A comma separated string of tag names to associate with the profile.
  • all_computers: Whether or not to associate this profile with all computers.

Example requests:

curl -X PATCH https://your-landscape.domain.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -d '{"description": "The stock image from the store", "tags": "windows_laptops"}'

Example output:

{
  "id": 2,
  "name": "stock-ubuntu-2404",
  "title": "Stock Ubuntu 24.04",
  "instance_type": "WSL",
  "description": "The stock image from the store",
  "image_name": "Ubuntu-24.04",
  "image_source": null,
  "cloud_init_contents": null,
  "cloud_init_secret_name": null,
  "tags": [
    "windows_laptops"
  ],
  "all_computers": false,
  "access_group": "global",
  "computers": {
    "constrained": [2, 3, 4, 5],
    "non-compliant": [3, 5],
    "pending": [4]
  }
}

POST /computers/<computer_id>/children

Creates an activity to install a WSL instance on a Windows host. The WSL instance will be managed in Landscape.

Required parameters:

  • computer_name

Optional parameters:

  • cloud_init
  • data_id
  • token
  • rootfs_url

Example requests:

curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Ubuntu-24.04"}'

curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Ubuntu-24.04", "data_id": "data-id", "token": "vault-token"}'

curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d "{\"computer_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < ~/cloud_init.yaml)\"}"

Example output:

{
  "id": 118,
  "creation_time": "2024-08-05T16:38:52Z",
  "creator": {
    "name": "John Smith",
    "email": "john@example.com",
    "id": 1
  },
  "type": "ActivityGroup",
  "summary": "Create instance Ubuntu-24.04",
  "completion_time": null,
  "parent_id": null,
  "deliver_delay_window": 0,
  "result_text": null,
  "result_code": null,
  "activity_status": "delivered"
}

Example request:

curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Custom-WSL-Image", "cloud_init": "<b64 encoded cloud_init file contents>", "rootfs_url": "https://example.com/custom_wsl_image.tar.gz"}'

Example output:

{
  "id": 118,
  "creation_time": "2024-08-05T16:38:52Z",
  "creator": {
    "name": "John Smith",
    "email": "john@example.com",
    "id": 1
  },
  "type": "ActivityGroup",
  "summary": "Create instance Custom-WSL-Image",
  "completion_time": null,
  "parent_id": null,
  "deliver_delay_window": 0,
  "result_text": null,
  "result_code": null,
  "activity_status": "delivered"
}

Notes:

  1. Sending both cloud_init and data_id will produce a 400 response.
  2. If rootfs_url is specified, then a 400 response is returned if the computer name matches any of the following case-insensitive patterns: Ubuntu, Ubuntu-Preview, Ubuntu-XY.ZW.

GET /wsl-instance-names

Gets a listing of valid WSL image names.

Required parameters:

  • None

Optional parameters:

  • None

Example request:

curl -X GET -H "Authorization: Bearer $JWT" "https://landscape.canonical.com/api/v2/wsl-instance-names"

Example output:

[
  {
	"name": "Ubuntu",
	"label": "Ubuntu"
  },
  {
	"name": "Ubuntu-22.04",
	"label": "Ubuntu 22.04"
  }
]