Update Edge Application Instances with Patch Envelopes

Patch Envelope is a feature of ZEDEDA Cloud that enables you to send data to a running application instance without shutting it down. The data you send can be anything that is consumable by the receiving app instance, including configuration updates, scripts, or small binary files. There are two types of data, inline and external: 

• Inline Data: To attach inline data, you copy and paste it into the appropriate field. Your data must be in Base64 format. This is ideal for small snippets of configuration, text files, or commands.
• External Data (Binary Artifact): This is the method for attaching larger scripts, certificates, or binary files. 

Additionally, by attaching an envelope to a group of app instances, you can simultaneously update all of them.

Note, however, that only apps connected to local network instances can receive patch envelopes. This is because the receiving app instances must be exposed to a metadata server.

Key Details about Patch Envelopes

• The size limit of an envelope is 5 MB.
• You can only attach an envelope to a single project.
• An app instance can only have one envelope attached at a time.
• An envelope can, however, be attached to many app instances.

Prerequisites

Format

When you use the ZEDEDA GUI, you can provide your artifact data in any format. You only need to be sure that your data are in the appropriate format for the receiving app instance.

When you use the ZEDEDA ZCLI or API, you'll also need to be sure that your envelopes are properly formatted in your requests. Refer to our API documentation for a JSON example of a patch envelope.

Prepare your data as an Inline Artifact

1. Save your data to a file, such as envelope_data.txt.
2. Open your terminal.
3. Encode the contents of envelope_data.txt to base64 with the following command.

   cat envelope_data.txt | base64

4. Copy the output of the previous command. This is what you need to provide when you create your inline artifact in the ZEDEDA GUI.

Prepare your data as an external Binary Artifact

To attach external data, you can upload or uplink a Binary Artifact from the Library > Binary Artifacts menu. 

• • Uplink refers to associating an entry in an enterprise with an artifact that is already stored in a data store. (You're basically registering the metadata for the image, such as its name, the title, description, image size, the data store where it is located, and its SHA256 checksum for verification. ZEDEDA will then use this information to create a reference to the binary file.
  • Upload refers to copying an artifact from your local machine to one of your ZEDEDA-managed data stores. In other words, placing the physical image file into the ZEDEDA-managed datastore. ZEDEDA will then use this information to create a reference to the binary file.

Add a Patch Envelope

When you create an envelope, you will first be prompted to provide a number of details. Then you'll be prompted to attach your data. Attached data is called an artifact.

1. Hover over Library on the left panel.
2. Click on Patch Envelopes.
3. Click the plus icon.
4. Fill in the Identity section.
   

   A few notable fields in the Details section are described in the following table.

   Activate Patch	You may activate an envelope either when you create it or at a later time.
   Name	This value can’t be changed after you create your envelope.

5. Fill in the Artifacts section, selecting inline or external from the Category drop-down.
6. Use the plus icon to add multiple artifacts.
7. When you are finished adding artifacts, click Add.

View Existing Patch Envelopes

To see a list of existing patch envelopes in your enterprise:

1. Hover on Library on the left side nav.
2. Click on Patch Envelopes.

View an App Instance’s Patch Envelope

1. Click on Edge App Instances on the left side nav.
2. Click on the edge app you want to check.
3. Click on the instance's Basic Info tab.
4. Observe the Patch Envelope field in the Details section.

View the patch envelope’s opaque status

Opaque status is the base64 encoded status message from the ZEDEDA GUI indicating that the data has been consumed by the receiving app instance.

From Edge App Instances > MY_INSTANCE > Status tab, you’ll see an opaque status messages such as the following:

c2FtcGxlIGRhdGE=

Attach or Detach an Envelope

1. Click on Edge App Instances on the left side nav.
2. Click on the app instance that you want to attach an envelope to.
3. Click on More Actions meatball icon.
4. Click Attach or Detach Patch Envelope.
5. Follow the prompts to complete the attachment or detachment.