Manage Patch Envelopes

Use the ZEDEDA CLI (ZCLI) to manage patch envelopes from the command line. This article covers zcli patch-envelope commands, with syntax and examples for each operation. A patch envelope is a versioned bundle of files, called artifacts, that Edge Infrastructure Services delivers to running application instances without redeploying them. Each patch envelope belongs to one project. An artifact is one of the following:

An inline artifact, which embeds a base64-encoded payload directly in the patch envelope.
An external artifact, which references a patch artifact image that is stored in a datastore. Use external artifacts for larger files.

Delivering files with a patch envelope takes the following steps:

For external artifacts, create a patch artifact image and add its file. See Create the Patch Artifact Image.
Describe the artifacts in an artifact configuration file. See Write the Artifact Configuration File.
Create the patch envelope with zcli patch-envelope create.
Attach the patch envelope to application instances with zcli edge-app-instance patch-envelope-attach. See Attach a Patch Envelope to Application Instances.
Set the patch envelope to the active state, if you did not create it active.

For the console procedures and background, see Update Applications with Runtime Bundles and Patch Envelopes.

Before You Start

ZCLI is installed and authenticated against your enterprise. See Get Started.
You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
The project that the patch envelope belongs to already exists. See Manage Projects.
The application instances that will receive the patch envelope belong to that project.

Patch Envelope States

The --action flag sets the state of a patch envelope. The console calls these states Active and Stored.

`--action` value	Console state	Description
`activate`	Active	The patch envelope delivers its artifacts to every application instance it is attached to.
`store`	Stored	The patch envelope is saved but does not deliver. Attached application instances do not receive its artifacts while it is stored.

ZCLI accepts the values in any letter case. Any other value prints Invalid value for --action parameter. Value should either be "store" or "activate" and ZCLI does not send the request.

Prepare the Artifacts

Create the patch artifact image

Skip this step if all your artifacts are inline. An external artifact references an image that you create with the --patch-artifact-image flag. Create the image record, then upload or uplink its file.

Create the image record:

zcli image create MY_PATCH_ARTIFACT --datastore-name=MY_DATASTORE --patch-artifact-image --image-format=raw

Upload the file:

zcli image upload MY_PATCH_ARTIFACT --path=./my-config-update.tar

Wait for the image status to change to READY. Then find the image ID, which the artifact configuration file needs:

zcli image show MY_PATCH_ARTIFACT --detail

The ID appears in the Image ID field. For details about patch artifact images, upload, and uplink, see Manage Images.

Write the artifact configuration file

zcli patch-envelope create reads the artifacts from a JSON file that you pass with --artifact-config-file. The file contains an artifacts list with one object for each artifact. The following example contains one external artifact and one inline artifact:

{
    "artifacts": [
        {
            "format": "OpaqueObjectCategoryExternalBinary",
            "binaryArtifact": {
                "imageName": "MY_PATCH_ARTIFACT",
                "imageId": "<image-id>",
                "fileNameToUse": "my-config-update.tar",
                "blobMetaData": "<blob-metadata>"
            },
            "artifactMetaData": "<artifact-metadata>",
            "id": "<artifact-id>"
        },
        {
            "format": "OpaqueObjectCategoryInline",
            "base64Artifact": {
                "base64Data": "YXJ0aWZhY3QgZGF0YQ==",
                "fileNameToUse": "settings.txt",
                "base64MetaData": "YXJ0aWZhY3QgbWV0YWRhdGE="
            },
            "artifactMetaData": "YXJ0aWZhY3QgbWV0YWRhdGE=",
            "id": "<artifact-id>"
        }
    ]
}

Field	Description
`format`	`OpaqueObjectCategoryExternalBinary` for an external artifact, or `OpaqueObjectCategoryInline` for an inline artifact.
`binaryArtifact`	External artifacts only. `imageName` and `imageId` identify the patch artifact image. `fileNameToUse` is the file name the artifact is written as. `blobMetaData` is optional metadata for the file.
`base64Artifact`	Inline artifacts only. `base64Data` is the file content, base64-encoded. `fileNameToUse` is the file name the artifact is written as. `base64MetaData` is optional metadata.
`artifactMetaData`	Optional metadata for the artifact.
`id`	Artifact ID. [TBD: confirm whether `id` is required in the artifact configuration file, and whether you supply a UUID or Edge Infrastructure Services generates one. ZCLI’s own test file supplies a UUID.]

To base64-encode a file for base64Data, run base64 -i settings.txt on macOS or base64 -w 0 settings.txt on Linux.

ZCLI sends the contents of the artifacts list exactly as written. It does not check the format values, encode the inline data, or look up the image ID from imageName. Copy the image ID from zcli image show --detail, and encode inline data yourself before you create the patch envelope.

ZCLI includes a sample artifact configuration file, patch-artifact-config.tmpl, but the sample has a trailing comma after the last artifact, which is not valid JSON. If you start from that sample, remove the trailing comma. ZCLI has no command to copy the sample, so the preceding example is a simpler starting point.

Create a Patch Envelope

Create a patch envelope in a project from an artifact configuration file.

zcli patch-envelope create <name> --title=<title> --user-defined-version=<user-defined-version> --action=<action> --project-name=<project-name> --artifact-config-file=<file-path> [--description=<description>]

Flag	Description
`<name>`	Required. Name of the patch envelope.
`--title`	Required. Display title of the patch envelope.
`--user-defined-version`	Required. Your own version label for the patch envelope, for example `1.0`. ZCLI does not check the format.
`--action`	Required. Initial state: `activate` or `store`. See Patch Envelope States.
`--project-name`	Required. Project that the patch envelope belongs to. You can attach the patch envelope only to application instances in this project.
`--artifact-config-file`	Required. Path to the artifact configuration file. See Write the Artifact Configuration File.
`--description`	Description of the patch envelope.

Example (create the patch envelope in the stored state, to activate it later):

zcli patch-envelope create MY_PATCH_ENVELOPE --title="Configuration update" --user-defined-version=1.0 --action=store --project-name=MY_PROJECT --artifact-config-file=./patch-artifacts.json --description="Updated settings file"

The artifact configuration file must be readable from inside the ZCLI container. See Work With Local Files.

If you create the patch envelope with --action=activate, it starts delivering as soon as you attach it to application instances. Use --action=store if you want to attach it first and activate it later.

If the artifact configuration file is not valid JSON, ZCLI prints the parse error and Invalid artifact config received, please input valid artifact configuration. and does not create the patch envelope. If the file has no artifacts list, ZCLI prints Unexpected error executing command 'patch-envelope' and does not create the patch envelope. If the file does not exist, ZCLI stops with a Python error. Check the path before you run the command.

View Patch Envelopes

View a single patch envelope

View one patch envelope by name or by ID. Unlike most ZCLI commands, show takes the name as the --name flag, not as a positional argument.

zcli patch-envelope show [[--name=<name> | --id=<id>] [--detail] | [[[--name-pattern=<name-pattern>] [--project-name-pattern=<project-name-pattern>] [--page-size=<page-size>] [--page-num=<page-number>]] | [--summary]]]

Flag	Description
`--name`	Name of the patch envelope.
`--id`	ID (UUID) of the patch envelope.
`--detail`	Show the full configuration, including every artifact.

To view a patch envelope by name:

zcli patch-envelope show --name=MY_PATCH_ENVELOPE

To view the full configuration of a patch envelope:

zcli patch-envelope show --name=MY_PATCH_ENVELOPE --detail

To view a patch envelope by ID:

zcli patch-envelope show --id=<id>

Without --detail, the output shows the name, ID, title, user-defined version, action, project name, and creation time. The action appears as the full API value, for example PATCH_ENVELOPE_ACTION_STORE. With --detail, the output also shows the following:

The description and the short action value, for example Store.
The project ID and project name.
Device Count, the number of edge nodes the patch envelope is attached to.
An Inline Artifacts table with each inline artifact’s ID, metadata, file name, and base64 data.
An External Artifacts table with each external artifact’s ID, artifact metadata, file name, image name, image ID, and blob metadata.
Version, the revision number that Edge Infrastructure Services increases each time the patch envelope changes. This is separate from the user-defined version.
Who created and last updated the patch envelope, and when.

The inline artifacts table prints the full base64 data of each inline artifact, so the output can be long. To read the configuration as JSON, run zcli --format=json patch-envelope show --name=MY_PATCH_ENVELOPE.

List patch envelopes

List all patch envelopes, or filter the list.

Flag	Description
`--name-pattern`	Show only patch envelopes whose name contains this text.
`--project-name-pattern`	Show only patch envelopes whose project name contains this text.
`--page-size`	Number of records for each request to Edge Infrastructure Services. The default is 500.
`--page-num`	Page number to show, where each page holds `--page-size` records.
`--summary`	Show only the count of patch envelopes by action, without the list. ZCLI ignores the other filters when you pass `--summary`.

The list shows the ID, name, title, user-defined version, action, and project name of each patch envelope, followed by a count by action. To list all patch envelopes:

zcli patch-envelope show

To list the patch envelopes in projects whose name contains MY_PROJECT:

zcli patch-envelope show --project-name-pattern=MY_PROJECT

To show only the count of patch envelopes by action:

zcli patch-envelope show --summary

Attach a Patch Envelope to Application Instances

ZCLI attaches and detaches patch envelopes with zcli edge-app-instance commands. The application instances and the patch envelope must belong to the project that you pass with --project.

Attach a patch envelope

zcli edge-app-instance patch-envelope-attach --app-instance=<name>... --project=<project> --patch-envelope=<patch-envelope>

Repeat --app-instance for each application instance. The following example attaches a patch envelope to two application instances:

zcli edge-app-instance patch-envelope-attach --app-instance=MY_APP_INSTANCE_1 --app-instance=MY_APP_INSTANCE_2 --project=MY_PROJECT --patch-envelope=MY_PATCH_ENVELOPE

Detach a patch envelope

zcli edge-app-instance patch-envelope-detach --app-instance=<name>... --project=<project>

The following example detaches the patch envelope from one application instance:

zcli edge-app-instance patch-envelope-detach --app-instance=MY_APP_INSTANCE_1 --project=MY_PROJECT

For details, see Manage Patch Envelopes in Manage Application Instances.

Update a Patch Envelope

Change the title, description, or state of a patch envelope.

zcli patch-envelope update <name> [--title=<title>] [--description=<description>] [--action=<action>]

Flag	Description
`<name>`	Required. Name of the patch envelope.
`--title`	New title.
`--description`	New description.
`--action`	New state: `activate` or `store`.

Activate a patch envelope

Set a stored patch envelope to the active state, so that it delivers its artifacts to the application instances it is attached to.

zcli patch-envelope update MY_PATCH_ENVELOPE --action=activate

To stop delivery without detaching the patch envelope, set it back to the stored state with --action=store.

update cannot change the artifacts, the user-defined version, or the project. To deliver different files, create a new patch envelope with a new artifact configuration file, attach it to the application instances, and then delete the old patch envelope. update also cannot clear the title or description. An empty value leaves the current value unchanged.

Delete a Patch Envelope

Delete a patch envelope by name.

zcli patch-envelope delete <name>

Example:

zcli patch-envelope delete MY_PATCH_ENVELOPE

delete does not ask for confirmation and has no -f flag. ZCLI deletes the patch envelope as soon as you run the command. Edge Infrastructure Services does not delete a patch envelope that is attached to edge nodes. Detach it from all application instances first.

Next Steps

Manage Images

Create the patch artifact images that external artifacts reference.

Manage Application Instances

Attach and detach patch envelopes on application instances.

Update Applications with Runtime Bundles

Create and manage patch envelopes and binary artifacts in the Edge Infrastructure Services console.

Overview

All ZCLI command procedures, organized by resource type.

Get started

Infrastructure

Applications

Monitoring and Usage

Administration and Marketplace

Before You Start

Patch Envelope States

Prepare the Artifacts

Create the patch artifact image

Write the artifact configuration file

Create a Patch Envelope

View Patch Envelopes

View a single patch envelope

List patch envelopes

Attach a Patch Envelope to Application Instances

Attach a patch envelope

Detach a patch envelope

Update a Patch Envelope

Activate a patch envelope

Delete a Patch Envelope

Next Steps

Manage Images

Manage Application Instances

Update Applications with Runtime Bundles

Overview

​Before You Start

​Patch Envelope States

​Prepare the Artifacts

​Create the patch artifact image

​Write the artifact configuration file

​Create a Patch Envelope

​View Patch Envelopes

​View a single patch envelope

​List patch envelopes

​Attach a Patch Envelope to Application Instances

​Attach a patch envelope

​Detach a patch envelope

​Update a Patch Envelope

​Activate a patch envelope

​Delete a Patch Envelope

​Next Steps

Manage Images

Manage Application Instances

Update Applications with Runtime Bundles

Overview

Before You Start

Patch Envelope States

Prepare the Artifacts

Create the patch artifact image

Write the artifact configuration file

Create a Patch Envelope

View Patch Envelopes

View a single patch envelope

List patch envelopes

Attach a Patch Envelope to Application Instances

Attach a patch envelope

Detach a patch envelope

Update a Patch Envelope

Activate a patch envelope

Delete a Patch Envelope

Next Steps