Skip to content

Latest commit

 

History

History
98 lines (75 loc) · 4.4 KB

PATCH-ENVELOPES.md

File metadata and controls

98 lines (75 loc) · 4.4 KB
Raw

Patch Envelopes

What is Patch Envelope?

Patch Envelope is a functionality in EVE that helps you change data in your App Instance in runtime without the need to reboot instance, or recreate image. Imagine that in order to change configuration in one of your program, you have to create new OS image and flush it to your computer. With Patch Envelope you don’t have to do that. Patch Envelope constitutes of Binary Artefacts (blobs) which are base64-encoded objects. This can be anything, from binary file to a configuration yaml file. Those Patch Envelopes are exposed to App Instance via Metadata server.

Why should I use it?

When recreating image doesn’t make sense (i.e. you just want to change one configuration parameter and you don’t want to recreate VM image) or when downtime is not an option for you

How can I use it?

In EVE every App Instance connected to local network instances is exposed to Metadata server at 169.254.169.254. It has bunch of useful endpoints, amongst them are patch envelope endpoints. So within App Instance one can access Patch Envelopes available to specific App Instance by getting description.json. This would return list of Patch Envelopes available to this App Instance.

curl -X GET -v http://169.254.169.254/eve/v1/patch/description.json
[

    {
        "PatchId":"699fbdb2-e455-448f-84f5-68e547ec1305",
        "Version":"1",
        "BinaryBlobs":[
            {
                "file-name":"textfile1.txt",
                "file-sha":"%FILE_SHA",
                "file-meta-data":"YXJ0aWZhY3QgbWV0YWRhdGE=",
                "url":"http://169.254.169.254/eve/v1/patch/download/699fbdb2-e455-448f-84f5-68e547ec1305/textfile1.txt"
            },
            {
                "file-name":"textfile2.txt",
                "file-sha":"%FILE_SHA%",
                "file-meta-data":"YXJ0aWZhY3QgbWV0YWRhdGE=",
                "url":"http://169.254.169.254/eve/v1/patch/download/699fbdb2-e455-448f-84f5-68e547ec1305/textfile2.txt"
            }
        ],
        "VolumeRefs":null
    }

]

Every Patch Envelope contains of one or more Binary Artefacts (Blobs) which are base64-encoded objects. Each object can be downloaded by calling URL, i.e.

curl -X GET http://169.254.169.254/eve/v1/patch/download/699fbdb2-e455-448f-84f5-68e547ec1305/textfile1.txt

will get you base64-encoded file.Note that you can download zip archive of all binary artifacts for a given patch envelope by calling

curl -X GET http://169.254.169.254/eve/v1/patch/download/699fbdb2-e455-448f-84f5-68e547ec1305 > a.zip

Flow diagram of the process is below

process-flow

Full OpenAPI (Swagger) specification for patch envelope endpoint can be found here. You can generate client from this specification and use it to develop your application.

What types of Binary Artifacts are there?

There’re two types of Binary Artifacts (Blobs): inline and external. There is no distinction in the API between internal and external artifacts from the application perspective. However, there’s a difference on how this artifacts are treated in EVE. Inline binary artifacts are small size artifacts (max 10KBytes) which are part of EdgeDevConfig, whereas external patch envelopes are represented as Volumes which are handled by volumemgr.

Where Binary Artifacts are stored?

Inline Artifacts are stored as part of EdgeDevConfig. External artifacts are stored in datastorage specified. EVE downloads artifacts directly from datastorage. Keep this in mind configuring ACLs and access.

How does it work?

patch-flow

Internally, Metadata Server stores envelopes which come from EdgeDevConfig parsed by zedagent. Binary Artifacts can be of two different types: inline and external. Metadata server stores VolRef – volume references, which are changed to BinaryBlobs once volumes are downloaded. Note that this process is async and it might take time. All communication in this process is done via PubSub. When AppInstance downloads inline object it’s served from Metadata server (zedrouter microservice). In case of external patch envelopes – Metadata serves file from volume. For more information on how it works in code refer here