appconfig.proto

// Copyright(c) 2017-2020 Zededa, Inc.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package org.lfedge.eve.config;
option go_package  = "github.com/lf-edge/eve-api/go/config";
option java_package = "org.lfedge.eve.config";

import "evecommon/acipherinfo.proto";
import "config/devcommon.proto";
import "config/storage.proto";
import "config/vm.proto";
import "config/netconfig.proto";

message InstanceOpsCmd {
  uint32 counter = 2;
  string opsTime = 4; // Not currently used
}

// Type of cloud-init data to provide to application
enum MetaDataType {
  MetaDataDrive = 0;
  MetaDataNone = 1; // Do not provide metadata
  MetaDataOpenStack = 2;
  MetaDataDriveMultipart = 3; // Process multipart MIME for application
}

// Type of the snapshot creation trigger
enum SnapshotType {
  SNAPSHOT_TYPE_UNSPECIFIED = 0;
  SNAPSHOT_TYPE_APP_UPDATE = 1; // Snapshot created as a result of an application update
  SNAPSHOT_TYPE_IMMEDIATE = 2; // Create snapshot immediately (may shutdown the running application)
}

// A descriptor of the snapshot instance
message SnapshotDesc {
  // id of the snapshot.
  // The format of the ID is a standard UUIDv4.
  // Should be unique within the app instance. Generated by the Controller in
  // the case the snapshot creation is requested by the Controller, or by EVE
  // in the case the snapshot creation is triggered locally.
  // Corresponds to the ZInfoApp.snapshots[].id field (see the `info.proto`
  // file).
  string id = 1;
  // type of the snapshot creation trigger.
  SnapshotType type = 2;
}

// The snapshot information for an Application Instance
message SnapshotConfig {
  // active_snapshot is the id of the snapshot which is expected to be used by
  // the application.
  // It may be empty if no snapshot expected to be used.
  string active_snapshot = 1;
  // rollback_cmd is used to trigger a rollback to the snapshot with the
  // active_snapshot id.
  // The counter inside the InstanceOpsCmd is incremented when a snapshot is
  // used for a rollback. It should not be decreased.
  // The counter's semantics is the same as the one used in the restart/purge
  // commands. It's necessary for the cases, when the state of the device is
  // behind the controller because it hasn't yet managed to fetch the latest
  // declarative statement. Only increasing the counter will trigger the
  // rollback.
  InstanceOpsCmd rollback_cmd = 2;
  // max_snapshots is the maximum number of snapshots that can be stored for the
  // application instance.
  // If the number of snapshots exceeds the max_snapshots, the oldest snapshot
  // will be deleted. It's so even if the oldest snapshot is the active one.
  // As an example, let's consider the following scenario:
  // The value of max_snapshots is 1. Then a snapshot is created. VM continues
  // working. Then a rollback to the snapshot created earlier is requested, so
  // the first snapshot becomes active. EVE performs the rollback. Then the
  // controller requests a new snapshot be created. EVE is configured to store
  // only 1 snapshot, hence the first one should be deleted.
  uint32 max_snapshots = 3;
  // snapshots is the list of snapshots of the application instance.
  // It is used to synchronize the list of snapshots between the controller and
  // the device. This can be used to provide an id of a new snapshot or to
  // delete an existing snapshot.
  // To provide a new snapshot id, the controller should send a message with
  // the new snapshot id in the snapshots list. The id is generated by
  // Controller in this case. (It can be also generated by EVE, if the snapshot
  // creation is triggered locally. In this case the ID will be returned in the
  // ZInfoApp.snapshots[].id field, see the `info.proto` file).
  // Worth noting that the snapshot creation is not triggered by the appearance
  // of the snapshot id in the available_snapshots list. The snapshot creation
  // will be triggered by the behaviour defined in the snapshot type field.
  // To delete a snapshot, the controller should send a message that does not
  // contain the snapshot id in the available_snapshots list. The device will
  // delete the snapshot with the absent id.
  repeated SnapshotDesc snapshots = 4;
}

// Type of app instance affinity
enum AffinityType {
  // Preferred - designated_node_id is preferred for placement but
  // if the node is unhealthy, app can run on other nodes.
  AFFINITY_TYPE_PREFERRED = 0;
  // Required - designated_node_id is required to be healthy for
  // app instance to boot, app will not failover to other nodes.
  AFFINITY_TYPE_REQUIRED = 1;
}

// The complete configuration for an Application Instance
// When changing key fields such as the drives/volumeRefs or the number
// of interfaces, the controller is required to issue a purge command i.e.,
// increase the purge counter. Otherwise there will be an error (The controller
// can also issue a purge command to re-construct the content of the first
// drive/volumeRef without any changes.)
// Some changes such as ACL changes in the interfaces do not require a restart,
// but all other changes (such as fixedresources and adapters) require a
// restart command i.e., an increase to the restart counter. The restart counter
// can also be increased to cause an application instance restart without
// any other change to the application instance.
message AppInstanceConfig {
  // deprecated fields
  reserved 14, 24;

  UUIDandVersion uuidandversion = 1;
  string displayname = 2; // User-friendly name
  VmConfig fixedresources = 3;

  // VolumeRefs, if supported by EVE, will supersede drives. Drives still
  // exist for backward compatibility.
  // Drives will be deprecated in the future.
  // The order here is critical because they are presented to the VM or
  // container in the order they are listed, e.g., the first VM image
  // will be the root disk.
  repeated Drive drives = 4;

  // Set activate to start the application instance; clear it to stop it.
  bool activate = 5;

  // NetworkAdapter are virtual adapters assigned to the application
  // The order here is critical because they are presented to the VM or
  // container in the order they are listed, e.g., the first NetworkAdapter
  // will appear in a Linux VM as eth0. Also, the MAC address is determined
  // based on the order in the list.
  repeated NetworkAdapter interfaces = 6;

  // Physical adapters such as eth1 or USB controllers and GPUs assigned
  // to the application instance.
  // The Name in Adapter should be set to PhysicalIO.assigngrp
  repeated Adapter adapters = 7;

  // The device behavior for a restart command (if counter increased)
  // is to restart the application instance
  // Increasing this multiple times does not imply the application instance
  // will restart more than once.
  // EVE can assume that the adapters did not change.
  InstanceOpsCmd restart = 9;

  // The EVE behavior for a purge command is to restart the application instance
  // with the first drive/volumeRef recreated from its origin.
  InstanceOpsCmd purge = 10;

  // App Instance initialization configuration data provided by user
  // This will be used as "user-data" in cloud-init
  // Empty string will indicate that cloud-init is not required
  // It is also used to carry environment variables for containers.
  // XXX will be deprecated and replaced by the cipherData below.
  string userData = 11;

  // Config flag if the app-instance should be made accessible
  // through a remote console session established by the device.
  bool remoteConsole = 12;

  // contains the encrypted userdata
  org.lfedge.eve.common.CipherBlock cipherData = 13;

  // The static IP address assigned on the NetworkAdapter which App Container
  // stats collection uses. If the 'collectStatsIPAddr' is not empty and valid,
  // it enables the container stats collection for this App.
  // During App instance creation, after user enables the collection of stats
  // from App, cloud needs to make sure at least one 'Local' type of Network-Instance
  // is assigned to the App interface, and based on the subnet of the NI, statically
  // assign an IP address on the same subnet, e.g. 10.1.0.100
  string collectStatsIPAddr = 15;

  // The volumes to be attached to the app-instance.
  // The order here is critical because they are presented to the VM or
  // container in the order they are listed, e.g., the first VM image
  // will be the root disk.
  // Note that since the name volumeRef was used before and deprecated
  // python protobuf seems to require that we use a different name.
  repeated VolumeRef volumeRefList = 16;

  // metadata type to use for app if provided inside userData
  MetaDataType metaDataType = 17;

  // profile_list is a set of strings which can be used to control which sets
  // of applications are run. Combined with the activate flag above.
  // If the profile list is empty it means wildcard; application will
  // be started independent of the global or local profile specified for the
  // device.
  repeated string profile_list = 18;

  // start_delay_in_seconds - Applicable only when EVE boots up fresh and starts
  // applications for the first time after boot up. This is the amount of time that
  // EVE waits (after boot finish) before starting each application.
  // Default value 0 -> start application immediately.
  // Non-Zero value -> After EVE is ready to start application instance, wait for the
  // given amount of time before starting the respective application instance.
  uint32 start_delay_in_seconds = 19;

  // service - run app instance as a service container in the host/dom0
  // will override default capabilities with configuration
  // defined in org.mobyproject.config label of image provided by linuxkit
  bool service = 20;

  // All changes to the cloud-init config are tracked using this version field -
  // once the version is changed cloud-init tool restarts in a guest.
  uint32 cloud_init_version = 21;

  // SnapshotConfig is used to track the snapshots of the app instance
  SnapshotConfig snapshot = 22;

  // PatchEnvelopeRef is used to track all patch envelopes used by the app instance
  PatchEnvelopeRef patchRef = 23;

  // Designated Node Id is used for cluster nodes to determine placement of
  // the AppInstance when an EdgeNodeCluster config is present.
  // See affinity below to set the desired node affinity.
  // eg. Preferred or Required.
  string designated_node_id = 26;

  // Custom resolution applies to VM that is running in FML mode only.
  string vm_resolution = 27;

  // AppRuntimeType - to indicate the types of Application Runtime Deployment
  AppRuntimeType runtime_type = 28;

  // Affinity is used for cluster nodes to determine
  // preferred or required node scheduling for app instances.
  // Node Id for scheduling is defined in designated_node_id.
  AffinityType affinity = 29;
}

message PatchEnvelopeRef {
  // one of them should be non-empty
  // non-empty name overrides the id
  string name = 23;
  string id = 24;
}

// Reference to a Volume specified separately in the API
// If a volume is purged (re-created from scratch) it will either have a new
// UUID or a new generationCount
message VolumeRef {
  string uuid = 1; // Volume UUID
  int64 generationCount = 2;
  // Indicates volume mount point inside container
  // if mount_dir is empty then it will be mounted on /mnt
  string mount_dir = 3;
}

// AppRuntimeType - to indicate the types of Application Deployment
// For instance, the need to gather of docker container metrics and logs
// from the agent inside applications on EVE device.
enum AppRuntimeType {
  APP_RUNTIME_TYPE_UNSPECIFIED = 0;
  APP_RUNTIME_TYPE_DOCKER = 1;
}