...

In the table below you can see the pros and cons:

It's also possible to combine apps and microservices in order to implement a single business solution:

...

• Sync communication - Typically used with RESTful services inside PIPEFORCE.

• Async communication - Typically used with RabbitMQ and messaging inside PIPEFORCE (preferred way).

Deploy / Start a Microservice​

Once a microservice has been developed, it must be wrapped inside a (Docker) image in order to be able to deploy it into PIPEFORCE. The deployment cycle of a microservice in PIPEFORCE is always an 4-step task:

1. Build a (Docker) container image from the sources of your microservice.

2. Upload the container image to a container registry which is supported by PIPEFORCE (for example Docker Hub or the PIPEFORCE Container Registry).

3. Deploy the image from this registry into your PIPEFORCE namespace by using the command service.start.

Step 2-4 These steps are typically automated by using a CI/CD tool like Jenkins, CircleCI, Travis or similar.

...

• service.start - Starts a new service by deploying an image.

• service.stop - Stops a running service.

• service.status - Returns the status of a service.

...

Default ENV variables​

Every time a service is started using the service.start command, also some implicit default variables will be automatically passed to this container and can be accessed via the environment variables inside the container. These implicit variables are:

...

...

...

...

PIPEFORCE_SERVICE = The name of this custom service inside PIPEFORCE.

...

...

...

...

...

...

...

...

Additionally to these default environment variables, you can also set your custom ones by using the parameter env on the command service.start:

pipeline:
  - service.start:
      name: myservice
      image: myimage
      env:
        MY_ENV: "myCustomValue"

Passing secrets as ENV​

...

Custom ENV variables

Additionally to these default environment variables, you can also add your custom ones by using the parameter env on the command service.start:

pipeline:
  - service.start:
      name: myservice
      image: myimage
      env:
        MY_ENV: "myCustomValue"

Secret ENV variables​

In case you would like to pass secret values to your service ENV variables, you have to do these steps:

1. Create a secret of type secret-text and with the service name as prefix in the secret store, like this: <yourservice>_<YOUR_SECRET_NAME>.

2. Use the custom uri $uri:secret:<yourservice>_<YOUR_SECRET_NAME> in the env parameter.

For example, lets assume you would like to start a service myservice and pass a secret with custom name MY_SERVICE to it. For this you have to create a secret with name myservice_MY_SECRET in the secret store and then refer to it like this:

pipeline:
  - service.start:
      name: myservice
      image: myimage
      env:
        MY_SECRET_ENV: $uri:secret:myservice_MY_SECRET

On startup of the service, the secret with name myservice_MY_SECRET will be read from the secret store and passed to the container as environment variable MY_SECRET_ENV. This way it is not required to store the secret in code.

You can also define a default value for a secret. In case the secret could not be found in the secret store, the given default value will be used and passed as ENV variable value instead:

$uri:secret:myservice_MY_SECRET:someDefaultValue

Shared secret ENV variables

In case you would like to share a single secret across multiple services, you must prefix it with SHARED_ instead. Secrets prefixed with SHARED_ can be passed to any microservice without security check.

Lets assume you have created a secret with name SHARED_MY_SECRET, then you can pass it to any service like this example shows:

pipeline:
  - service.start:
      name: myservice
      image: myimage
      env:
        MY_SECRET_ENV: "$uri:secret:MY_SECRET"

On startup of the service, the secret with name MY_SECRET will be read from the secret store and passed to the container as environment variable MY_SECRET_ENV. This way it is not required to store the secret in code.

You can also define a default value for a secret. In case the secret could not be found in the secret store, the given default value will be used and passed as ENV variable value instead:

$uri:secret:MY_SECRET:someDefaultValue:SHARED_MY_SECRET

Monitoring a microservice​

...

If you're interested in how to send and receive messages using pipelines, see Messaging and Events Framework.

How to connect a Microservice with the message broker?​

...

• PIPEFORCE_MESSAGING_HOST = The cluster-internal hostname of the messaging service.

• PIPEFORCE_MESSAGING_PORT = The cluster-internal port of the messaging service.

Additionally to these variables, you need to set the PIPEFORCE_MESSAGING_USERNAME and PIPEFORCE_MESSAGING_PASSWORD along with your service.start command using the custom uri prefix $uri:secret. Here is how to do it:

1. Create a new secret in your secret store with name pipeforce-<yourservice>_messaging-_username and type secret-text and set the RabbitMQ username you would like to use to connect.

2. Create a new secret in your secret store with name pipeforce-<yourservice>_messaging-_password and type secret-text and set the RabbitMQ password you would like to use to connect.

...

pipeline:
    - service.start:
        name: "myservice"
        image: "some/image"
        env:
            PIPEFORCE_MESSAGING_USERNAME: "$uri:secret:pipeforce-myservice_messaging-username"
            PIPEFORCE_MESSAGING_PASSWORD: "$uri:secret:pipeforce-myservice_messaging-password"

This way, the sensitive values will be passed to your container without the requirement to store them into code or refer from external systems.

...

By default any microservice is responsible to setup and manage its own queues.

Each queue should contain always equal message types. So, for different messages, create additional queues.

...

service_shoppingcart_orders_q

Default Topic​

PIEPFORCE PIPEFORCE automatically creates a default topic exchange on startup with this name: pipeforce.hub.default.topic.

PIPEFORCE core services are configured in a way that any event which happens there or which is sent using the event.send command is will also be send to this default topic.

In case a microservice wants to listen to a certain type of message with a given routing key, it needs to create a binding between the topic pipeforce.hub.default.topic and the queue you want to “feed” this message into.

See here for more details about topics, routings and queues: https://www.rabbitmq.com/tutorials/tutorial-five-python.html

...

Additionally, a default Dead Letter Queue is automatically configured by PIPEFORCE : pipeforce_hub_default_dlqthose name is given by the ENV variable PIPEFORCE_MESSAGING_DEFAULT_DLQ.

Any other queue can be configured in a way to forward messages to this queue if one these rules apply:

...

x-dead-letter-exchange = ""
x-dead-letter-routing-key = "pipeforce_hub_default_dlq"

How to set these arguments in your microservice depends on your selected programming language and the RabbitMQ client implementation you're using. See documentation for details: https://www.rabbitmq.com/dlx.html

...

See here for more details about message key patterns on topics: https://www.rabbitmq.com/tutorials/tutorial-five-python.html