Configuring Triton packages

Modified: 26 Jan 2023 22:12 UTC

Here are instructions for how to configure packages in Triton. Provides detail on the creation, deletion, and modification of packages both via PAPI and the Operations Portal.

To learn more about sizing packages for your application, read our sizing guidelines.

Package definitions

There are a number of fields on the Create Package page (which correspond to fields in the API) and, with the exception of Owner and Description they are all required.

Field Description Notes
Name Name of package in API. This value is used via the triton CLI tool.
Description Human readable description of this package. This should be descriptive enough to help both end users and operators understand the package.
Version Package version number. Once created, a package cannot be changed; a new version must be created.
Owners UUID's of package owner(s). Packages without an owner assigned are public; packages with an owner are only available for provisioning by the owner(s)
Memory Max RAM in MiB. Should be a multiple of 2.
Swap Max Swap in MiB. Should be a multiple of 2; must be equal to 2x Memory or more.
Number of CPUs Number of cpus to show, between 1 - 64. Required during provisioning if type == 'kvm' or 'bhyve'. Only used for HVMs.
CPU Cap Cap on how much CPU an instance can use. 100 = one core, 350 = 3.5 cores, etc.
Max Lightweight Processes Max number of processes allowed. Only applies to infrastructure containers running SmartOS; Hardware virtual machines all run under one qemu process.
Disk Quota Disk size in MiB. For containers, this is a quota. For HVM instances, all disk is allocated at once as a ZVOL.
IO Priority ZFS I/O priority. This operates relative to other instances on a compute node, determining which get I/O first. This value is relative to other instances on a compute node.
Activate Package Boolean to tell whether it can currently be used for provisioning. Inactive packages can still be in use (ie, have instances provisioned using them).
Default Package Whether this is the default package of this name through the SDC 6.5 API. This is a holdover from SDC 6.5, and can be ignored in Triton installations.

Note: It is highly recommended that all numeric values (memory, swap, disk) are assigned as multiples of two. Not doing so can cause issues with various system utilities.

Managing packages {#managingpackagesportal} in the operations portal

Log in to the Operations Portal using Operator credentials. Navigate to the Packages page:

The Packages page displays all packages currently available in the system, the status (Active or Inactive), the current version, and the amount of RAM and Disk assigned to the package:

Create package

  1. To begin creating a package, click Create Package, located at the upper right corner of the Packages.
  2. Once you have entered the package details, click the Create Package button at the bottom of the page.

If there are any errors on the page, the Operations Portal will refuse to create the package and will inform you of your error with both red text and red highlighting around the problem section. Correct these errors and click on Create Package to create the packages.

Once you create a package, you can modify the description, group name, version number, and package owners fields. You can also activate/deactivate the package as well as make the package the default choice.

Some fields cannot be changed once you create a package. In order to change fields such as Name, Memory, Swap, vCPUs, Max Threads, Disk Quotas, IO Priority, and Brand, you will need to create a new version of the package.

The following images highlights the editable fields in blue. Fields that you can't change are highlighted in red:

Note: If a package is intended to be used with only one brand (e.g. kvm orbhyve) the optional brand should be set to kvm (or bhyve). See Package details for more information about how to set the attribute values.

Reviewing the new package

Once the package has been successfully created, you are returned to the Packages page with the focus set to the newly created package:

From the details page, you can:

Flexible disk space

Operators must create new packages when enabling the Flexible Disk option so that users can take advantage of the tools. If the Brand and Flexible disk options are not configured as part of the package, the instances created using the new package cannot be resized.

To set up an environment to use the resizing feature with Bhyve instances, Operators will need to update to minimum required versions, enable snapshots, and create packages. Older PI version do not support flexible disk space.

Update Admin UI and Triton components

Enable snapshots

To enable the snapshot feature, from the head node, add the following SAPI configuration:

    # cloudapi_svc=$(sdc-sapi /services?name=cloudapi | json -H 0.uuid)
    # sapiadm update "$cloudapi_svc" metadata.experimental_cloudapi_bhyve_snapshots=true

Once enabled, users should now be able to create snapshots of their bhyve instances.

Create flexible disk packages

To create packages for resizable Bhyve instances:

  1. Select the configuration options required for your environment.
  2. In Optional Settings, set the Brand to "bhyve" and set Flexible Disk to "true".

The following image shows an example of bhvye package configuration:

Adding additional disks In bhyve, the package space adds two disks. As an admin, you can now add up to 6 additional disks for a total limit of 8. For information on how to add additional disks, see Sizing your application.

Modifying a package

In order to modify a package, you must create a new version of the package. This is to maintain consistency within Triton. To assist you with this task, there is a Create New Version button located on the detail page for each package. Additionally, all versions of a package and their status are shown on this page. Clicking on a version will show the details for that version:

When you click on the Create New Version button, you will be taken to the Create Package page which will be populated with the data from the version of the package you are currently viewing. However, you will also be informed that you will need to select a new, unique (within the package) version number for the updated package:

Once the new version is created, it will be available for provisioning provided the Activate property has been set.

Deactivate package

Packages are never deleted, but they can be set to Inactive. Doing so prevents them from being used to provision new instances.

To accomplish this, navigate to the package you wish to inactive and make sure you click on the version number you wish to deactivate, then click on the Package Settings button:

This will bring up a screen that allows you to modify the only parts of the package definition that are allowed (Description, Group, Owner(s), Active, and Default):

If you uncheck the Activate Package checkbox and click Save Package the package will be marked as inactive. This will not affect currently provisioned instances, but will prohibit new instances from being provisioned with this package.

You can use this API endpoint to interact with the PAPI core serivce.

Note: For applications where you do not care about the return codes or other header information, you can pass the --no-headers option to sdc-papi to have it suppress header information. However, there are some times - such as during the create process - where you are going to want to see that information, which is also useful in diagnosing problems.

Viewing a package

To view the details on a package with a known UUID, you simply call sdc-papi and provide the UUID as shown:

headnode# sdc-papi /packages/3cb669ab-f550-4a35-90e1-f1593b799f2b
HTTP/1.1 200 OK
request-id: 3cb669ab-f550-4a35-90e1-f1593b799f2b
Content-Type: application/json
Content-Length: 655
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, PUT, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: 72CxaSgrVNrqkJmEjkuBjg==
Date: Fri, 02 May 2014 14:51:08 GMT
Server: SDC Package API 7.0.0
Api-Version: 7.0.0
Response-Time: 7

{
  "active": true,
  "common_name": "High CPU 4",
  "cpu_burst_ratio": 1,
  "cpu_cap": 500,
  "description": "High CPU 4 GB RAM 4 vCPUs and bursting 150 GB Disk",
  "fss": 500,
  "max_lwps": 4000,
  "max_physical_memory": 4096,
  "max_swap": 8192,
  "name": "g3-highcpu-4-smartos",
  "overprovision_cpu": 1,
  "overprovision_memory": 1,
  "quota": 153600,
  "ram_ratio": 0.8,
  "uuid": "3cb669ab-f550-4a35-90e1-f1593b799f2b",
  "version": "1.1.0",
  "zfs_io_priority": 600,
  "networks": [
    "42325ea0-eb62-44c1-8eb6-0af3e2f83abc",
    "c8cde927-6277-49ca-82a3-741e8b23b02f"
  ],
  "created_at": "2014-03-19T05:12:22.754Z",
  "updated_at": "2014-04-17T20:12:52.132Z",
  "billing_tag": "g3-highcpu-4-smartos",
  "default": false,
  "group": "High CPU",
  "v": 1
}

Searching for a package

You can supply a search string to sdc-papi that will permit you to search through the stored package data. For example, to find a package named sdc_128 you can:

headnode# sdc-papi --no-headers /packages?name=sdc_128
[
  {
    "active": true,
    "cpu_cap": 100,
    "max_lwps": 1000,
    "max_physical_memory": 128,
    "max_swap": 256,
    "name": "sdc_128",
    "quota": 25600,
    "uuid": "73a1ca34-1e30-48c7-8681-70314a9c67d3",
    "vcpus": 1,
    "version": "1.0.0",
    "zfs_io_priority": 10,
    "owner_uuids": [
      "9dce1460-0c4c-4417-ab8b-25ca478c5a78"
    ],
    "created_at": "2014-03-19T05:12:25.087Z",
    "updated_at": "2014-04-17T20:13:32.011Z",
    "billing_tag": "joyent-internal",
    "default": true,
    "v": 1
  }
]

PAPI also allows searching for multiple values per attribute. For example, if you're looking for all packages with the name "sdc_256" and "sdc_1024", then encode the alternatives into a JSON array and provide that as the argument:

headnode# sdc-papi /packages?name=["sdc_256","sdc_1024"]

The above will return any package that has either "sdc_256" or "sdc_1024" as a name. This can be used to search any attributes with type float, double, number, string, and boolean.

It is possible to search for matches within arrays. As an example, the networks attribute can store several values. If you'd like to search for all packages that use either the 33458263-d400-4a8b-8766-c260affa58f4 or 8582fa4e-8c57-49ce-ace5-3aa96ec0a792 networks, then:

headnode# sdc-papi /packages?networks=["33458263-d400-4a8b-8766-c260affa58f4","8582fa4e-8c57-49ce-ace5-3aa96ec0a792"]

PAPI also supports wildcards. To search for all packages starting with the name sdc_:

headnode# sdc-papi /packages?name=sdc_*

Also, you can combine these searches. So to search for all of the above:

headnode# sdc-papi /packages?version=1.0.1&name=sdc_*&networks=["33458263-d400-4a8b-8766-c260affa58f4","8*"]

Creating a package

You can use the sdc-papi API to create packages using a json payload. In the example below, we are creating a test package on the head node.

Once the command has been processed, it will return a 201 code for success and provide the json detail for the newly created package.

headnode# sdc-papi /packages -X POST -d '{ "name": "test-high2-kvm", \
"version": "1.0.0", "active": true, "vcpus": 2, "cpu_cap": 200, \
"description": "Test High CPU Package", "max_lwps": 4000, \
"max_physical_memory": 2048, "max_swap": 4096, "quota": 153600, \
"zfs_io_priority": 200, "default": false, "v": 1 }'

HTTP/1.1 201 Created
Location: /packages/19c608e5-e718-c44a-f704-86125ddd8d2f
request-id: 19c608e5-e718-c44a-f704-86125ddd8d2f
Content-Type: application/json
Content-Length: 362
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, POST
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: 5kV9M9C4I7lRdDzS/4RHsw==
Date: Fri, 02 May 2014 12:24:51 GMT
Server: SDC Package API 7.0.0
Api-Version: 7.0.0
Response-Time: 113

{
  "name": "test-high2-kvm",
  "version": "1.0.0",
  "active": true,
  "vcpus": 2,
  "cpu_cap": 200,
  "description": "Test High CPU Package",
  "max_lwps": 4000,
  "max_physical_memory": 2048,
  "max_swap": 4096,
  "quota": 153600,
  "zfs_io_priority": 200,
  "uuid": "19c608e5-e718-c44a-f704-86125ddd8d2f",
  "created_at": "2014-05-02T12:24:51.421Z",
  "updated_at": "2014-05-02T12:24:51.421Z",
  "default": false,
  "v": 1
}

Modifying a package

There are only certain properties that can be modified on a package, including description, active flag, and default flag. These can all be adjusted from the sdc-papi command. For example, to set a package inactive:

headnode# sdc-papi /packages/3bfcd25a-d867-cc31-f906-853eb222d6fe -X PUT -d '{ "active": "false" }'
HTTP/1.1 200 OK
request-id: 3bfcd25a-d867-cc31-f906-853eb222d6fe
Content-Type: application/json
Content-Length: 362
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, PUT, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: MVr+aW0D8LFH5Zhbg1ODSQ==
Date: Fri, 02 May 2014 18:17:58 GMT
Server: SDC Package API 7.0.0
Api-Version: 7.0.0
Response-Time: 91

{
  "name": "test-package",
  "version": "1.0.0",
  "active": false,
  "vcpus": 2,
  "cpu_cap": 200,
  "description": "Test Creating a Package",
  "max_lwps": 4000,
  "max_physical_memory": 1024,
  "max_swap": 2048,
  "quota": 4096,
  "zfs_io_priority": 100,
  "uuid": "3bfcd25a-d867-cc31-f906-853eb222d6fe",
  "created_at": "2014-05-02T12:50:25.420Z",
  "updated_at": "2014-05-02T18:17:57.958Z",
  "default": false,
  "v": 1
}

Mirroring packages between data centers

If you are running multiple data centers, it is possible to move packages between the data centers using JSON output.

Export the data from the source data center:

headnode# sdc-papi /packages?name=std-1gb | json -aH
{
  "uuid": "4673ce83-75eb-e69c-adff-84a62c4c3eab",
  "name": "std-1gb",
  "version": "1.0.0",
  "active": true,
  "vcpus": 1,
  "cpu_cap": 100,
  "description": "",
  "max_lwps": 4000,
  "max_physical_memory": 1024,
  "max_swap": 2048,
  "quota": 10240,
  "zfs_io_priority": 1,
  "created_at": "2014-07-31T07:26:55.970Z",
  "updated_at": "2014-08-01T09:25:01.252Z",
  "default": false,
  "v": 1
}

Note: The name search accepts wild cards, e.g. sdc-papi /packages?name=std* | json -aH so you should be able to extract all your packages in a few well crafted API calls. With this method, each package has to be created on the destination with individual API calls.

Now import the data on the destination:

headnode# sdc-papi /packages -X POST -d '  {
     "name": "std-1gb",
     "version": "1.0.0",
     "active": true,
     "vcpus": 1,
     "cpu_cap": 100,
     "description": "",
     "max_lwps": 4000,
     "max_physical_memory": 1024,
     "max_swap": 2048,
     "quota": 10240,
     "zfs_io_priority": 1,
     "uuid": "4673ce83-75eb-e69c-adff-84a62c4c3eab",
     "created_at": "2014-07-31T07:26:55.970Z",
     "updated_at": "2014-07-31T07:26:55.970Z",
     "default": false,
     "v": 1
   }'

HTTP/1.1 201 Created
request-id: 4673ce83-75eb-e69c-adff-84a62c4c3eab
Location: /packages/4673ce83-75eb-e69c-adff-84a62c4c3eab
Content-Type: application/json
Content-Length: 332
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, POST
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: Plkau0PdF81T0hnS5UlGPg==
Date: Fri, 01 Aug 2014 09:25:01 GMT
Server: SDC Package API 7.0.0
Api-Version: 7.0.0
Response-Time: 172

{
  "uuid": "4673ce83-75eb-e69c-adff-84a62c4c3eab",
  "name": "std-1gb",
  "version": "1.0.0",
  "active": true,
  "vcpus": 1,
  "cpu_cap": 100,
  "description": "",
  "max_lwps": 4000,
  "max_physical_memory": 1024,
  "max_swap": 2048,
  "quota": 10240,
  "zfs_io_priority": 1,
  "created_at": "2014-07-31T07:26:55.970Z",
  "updated_at": "2014-08-01T09:25:01.252Z",
  "default": false,
  "v": 1
}

Note: UUIDs will be retained providing they don't conflict with existing objects. If you hit a conflict remove the uuid field from the JSON and re-run the command; a new UUID will be generated for you.

What do you want to do next?