App YAML definition

Darcy Cloud uses Eclipse ioFog under the covers to deploy and manage applications , and all Darcy applications are deployed to edge node(s) via a YAML configuration file.

We directly use the ioFog YAML specifications for defining different resource Kinds. For application deployments, the Kind in the YAML file will always be Application. In this section, you’ll find an example application YAML file and description of all fields supported by Darcy Cloud.

Fields

FieldDescription
apiVersionSpecifies the version of ioFog API to be used by the application and microservices . The different versions of the ioFog API can be found in the documentation , and in general the latest version should be used.
kindDefines what is being deployed to the node(s). For the Darcy Cloud deployments, the kind will always be Application (although ioFog accepts many other kind types).
metadataThe metadata object is a place to specify pertinent Application information. The main thing to be specified in the metadata specification for Darcy Cloud applications is the name of the application.
metadata.nameThe name of the application. This has to be unique within the namespace of the edge project . The name of the application must start and end with lowercase alphanumeric characters, and it can include the - character.
specObject containing actual specifications of the application being deployed to the Darcy Cloud. For applications, the main specs to define are the microservices that compose the application, and the routes between the microservices.
spec.microservicesObject containing the microservices that make up your application. See the microservices section below for more information.
spec.routesA list of Application Routes. Application routes define message passing between microservices. From and To use microservice names as identifiers, and must match a microservice defined in the microservices section. When deploying an application, prefer this method to the microservice route field.

Microservices

Microservices are the core components of the Darcy Cloud application. Microservices configuration and set up are defined inside the application YAML files. Darcy Cloud allows for several microservices to be configured within the same YAML file, and these microservices can be assigned to any of the available nodes in the project.

FieldDescription
nameThe name of the microservice. This has to be unique within the list of the microservices in the application. The name of the microservice must start and end with lowercase alphanumeric characters, and it can include the - character.
agentThe agent object is used to specify information about the node the microservice is to be deployed on. By default, the YAML file can specify the the node name generically using YAML templating. See the Application Templating section for a more detailed explanation about this field.
agent.nameThe name of the Darcy Cloud node that the microservice should be deployed to.
images

The images object is used to specify the location of the x86 and arm container images to be used by the node running the microservice

It is currently required to set both an x86 and an arm container image for the microservice. This allows the same application can be deployed across a variety of hardware.

images.x86Container image to be used on node(s) using an x86 processor.
images.armContainer image to be used on node(s) using an ARM processor.
images.registryThe image registry specifies how the node should access the microservice x86 and ARM container images. The registry can be set to either local, remote, or to a specific Darcy registryID. More information about the Darcy registry can be found in the Registries section or in the ioFog documentation .
configUser-defined arbitrary object to be passed to the microservice runtime as its configuration. This is similar to the microservice’s environment variable section, only the variables set in the config will be encrypted so that only other microservices can access them. This adds a layer of security to the fields, so this is the typical place to store secrets as it’s safer. Using config does require changing the actual code in the microservice to be able to handle the config variables.
containerThis variable is used to specify the configuration of the container that wraps the images.
container.rootHostAccessThis variable is the same as the privilege mode on Docker; when it is set to true, the container will be able to access the host. This will also set the network of the container to host. See the Docker to Darcy section for a more detailed explanation about this field.
container.portsList of port mapping to be provided to the container running the microservice. See the Docker to Darcy section for a more detailed explanation about this field.
container.ports.externalThe external port exposed to the node.
container.ports.internalThe internal port used by the microservice.
container.ports.protocolThe protocol used to send data between the internal and external ports via a proxy tunnel. The choices for the field are http (the default) or tcp.

| container.volumes | List of volume mapping to be provided to the container running the microservice. See the Docker to Darcy section for a more detailed explanation about this field. | | container.volumes.hostDestination | Specifies where a volume directory is on the host’s external operating system.
The volume specified must be available on the host; microservices are not able to create volumes on the host. | | container.volumes.containerDestination | Specifies where a volume directory is on a container’s operating system. | | container.volumes.accessMode | The type of access the microservice should have to the volume. The choices for this field are the standard w (write), ro (read-only), rw (read-write), etc.. | | container.volumes.type | The type of the mount being specified. The choices are either bind (the default) or volume. bind mounts are files mounted from the host machine onto the container. A volume mount is a separate storage space managed by a different container or service like Docker. | | container.env | A list of environment variables to be provided to the container running the microservice. | | container.env.key | The name of the environment variable. | | container.env.value | The value of the environment variable. | | container.commands | A list of command line style arguments passed to the container at runtime. |

Routes

Application routes define message passing between microservices. Routing in Darcy Cloud applications is special in that it allows for an end-to-end encrypted, secure way for microservices to communicate with each other through the cloud.

Darcy Cloud provides an API to publish data to and to read data from so that a specific applications microservices can communicate with each other through generic “service” microservices run in the background by the Darcy Cloud control plane.

Because it is necessary to change the code in the actual images in order to utilize routing, likely routing will not be implemented when moving an existing cloud project to the Darcy Cloud.

FieldDescription
routes.nameThe name of the route being defined to pass messages or data between specified microservices. The name of the route must start and end with lowercase alphanumeric characters, and it can include the - character.
routes.fromThe name of the microservice that data will be routed from.
routes.toThe name of the microservice that data will be routed to.

Example YAML

apiVersion: iofog.org/v3
kind: Application
metadata:
  name: my-application-name
spec:
  microservices:
    agent:
      name: zebra-1
    images:
      x86: edgeworx/healthcare-heart-rate:x86-v1
      arm: edgeworx/healthcare-heart-rate:arm-v1
      registry: remote
    config:
      data_label: test_mode=false_cross_agent_microservice_routing_aug_27
      test_mode: trueYaml
    container:
      rootHostAccess: false
      volumes:
        - hostDestination: /tmp/msvc
          containerDestination: /data
          accessMode: "rw"
          type: "bind"
      env:
        - key: BASE_URL
          value: http://localhost:8080/data
      ports:
        - internal: 80
          external: 5000
          protocol: http
          public: 14341
      commands:
        # This will result in the container being started as
        # `docker run <image> <options> dbhost localhost:27017`
        - "dbhost"
        - "localhost:27017"
  routes:
    - name: monitor-to-viewer
      from: heart-rate-monitor
      to: heart-rate-viewer