<commit_before>---
date: 2016-09-13T09:00:00+00:00
title: Merge and delete
menu:
  main:
    parent: "Tutorials"
    weight: 50
---

In the [previous tutorial we "over-engineered" our service based solution a bit](/documentation/tutorials/split-a-monolith/) (on purpose of course). We don't really need two backends services, so in this tutorial we will introduce our newly engineered solution and transition to it using Vamp blueprints and canary releasing methods. In this tutorial we will:

* Get some background and theory on merging services
* Prepare our blueprint
* Merge the blueprint with a running deployment
* Decommision parts of the deployment
* Answer the all important question _when would I use this?_

**Requirements:** Docker machine should have access to **at least 3GB memory**

## Some background and theory

What we are going to do is create a new blueprint that is completely valid by itself and merge it
with our already running deployment. This might sound strange at first, but it makes sense. Why? Merging will enable us to slowly move from the previous solution to the next solution. Once moved over, we can
remove any parts we no longer need, i.e. the former "over-engineered" topology.

![](/images/screens/v094/services_atob.png)

In the diagram above, this is visualized as follows:

1. We initiate a running deployment by deploying Blueprint A 
* We introduce a new service to the deployment by merging Blueprint B with the running deployment
* At this point, both blueprints are active allowing for a smooth transition. For example by canary release
* Once we are fully on running on Blueprint B, we can remove/decommission Blueprint A

## Prepare our blueprint

The below blueprint describes our more reasonable service topology. Again, this blueprint is completely
valid by itself. You could just deploy it somewhere separately and not merge it with our over-engineered
topology. Notice the following:

- There is only one backend cluster with one service
- There is no gateway specified. This is because we will use the gateway already present and configured in the running deployment. It would be perfectly correct to specify the old gateway, just not necesary.

```
name: sava:1.3
clusters:
  sava: # cluster 1
    services:
      breed:
        name: sava-frontend:1.3.0
        deployable: magneticio/sava-frontend:1.3.0
        ports:
          webport: 8080/http
        environment_variables:
          BACKEND: http://$backend.host:$backend.ports.webport/api/message
        dependencies:
          backend: sava-backend:1.3.0
      scale:
        cpu: 0.2
        memory: 64MB
        instances: 1
  backend: # cluster 2
    services:
      breed:
        name: sava-backend:1.3.0
        deployable: magneticio/sava-backend:1.3.0
        ports:
          webport: 8080/http
      scale:
        cpu: 0.2
        memory: 64MB
        instances: 1
```

## Merge the blueprint

We can merge our new blueprint with the running sava:1.2 deployment in the same way we approached the merge in the [run a canary release tutorial](/documentation/tutorials/run-a-canary-release/).  This will deploy the new sava:1.3. services alongside sava:1.2, without routing any traffic to them.  
You can do this using either the Vamp UI or API.

### Merge using the Vamp UI

1. Go to the **Blueprints** page and click **Add** (top right)
* Paste in the above blueprint and click **Save**. Vamp will store the blueprint and make it available for deployment 
* Open the action menu on the **sava:1.3** blueprint and select **Merge to** 
  ![](/images/screens/v094/tut4_merge.png)
* You'll be prompted to select the deployment you wish to merge the blueprint with - select **sava:1.2**
* Click **Merge** to deploy the services sava:1.3 and sava-backend:1.3 to the running sava:1.2 deployment.  

### Merge using the API

You can complete the same merge action with the Vamp API - remember to set the `Content-Type: application/x-yaml` for your requests:

1. To create the blueprint, `POST` the above blueprint YAML to `/api/v1/blueprints`  
* To merge the blueprint, `PUT` the below YAML to `/api/v1/deployments/sava:1.2`  

  ```
  name: sava:1.3
  ```

![](/images/screens/v094/tut4_merged_deployment.png)

Notice we now have:

* Three backend clusters: two old ones (backend1 and backend2) and one from the new merge.
* Two services in the sava cluster: the old sava-frontend:1.2 and the new sava-frontend:1.3.  
  If you open the sava cluster **webport** you will see that the sava-frontend:1.2.0 route has a weight of 100% and the new new sava-frontend:1.3.0 route has a weight of 0%. Whenever Vamp merges a new service to an existing cluster it applies the default weight of 0%. This means no traffic will be routed to sava:1.3 yet.

![](/images/screens/v094/tut4_route_weights.png)

So what happened here? Vamp worked out which parts of the blueprint were already in the deployment and which parts should be added. This is done based on naming:

* The sava cluster already existed, so Vamp added a service to it with 0% route weight
* A cluster named "backend" didn't exist yet, so it was created 

Now we have both blueprints deployed, moving from the old to the new topology is just a question of “turning the weight dial”. You could do this in one go, or slowly adjust it. 

![](/images/screens/v094/tut4_sava_weight.png)

## Decomision parts of the deployment

Once we are fully running on sava:1.3, we can decommision the old, over-engineered sava:1.2.  We do this by updating the deployment again, this time to remove the sava:1.2 blueprint, effectively deleting all deployed sava:1.2 services. 

### Delete using the Vamp UI

1. Go to the **Blueprints** page  
* Open the action menu on the **sava:1.2** blueprint and select **Remove from** 
  ![](/images/screens/v094/tut4_delete.png)
* You'll be prompted to select the deployment you wish to remove the blueprint from - select **sava:1.2**
* Click **Remove** to delete the services sava:1.2, sava-backend1:1.2 and sava-backend2:1.2 from the running sava:1.2 deployment.   
  
### Delete using the API

You can complete the same delete action with the Vamp API - remember to set the `Content-Type: application/x-yaml` for your requests:

1. To delete the sava:1.2 blueprint from the deployment, `DELETE` the below YAML to `/api/v1/deployments/sava:1.2`  

  ```
  name: sava:1.2
  ```

![](/images/screens/v094/tut4_after_delete.png)

Vamp will update the running deployment, removing all elements described in the sava:1.2 blueprint. This means that our running deployment **sava:1.2** now contains no sava:1.2 services - that's why including a version number in the name of a mutable deployment is a bad idea.
<commit_msg>small edit to revised tutorial<commit_after>---
date: 2016-09-13T09:00:00+00:00
title: Merge and delete
menu:
  main:
    parent: "Tutorials"
    weight: 50
---

In the [previous tutorial we "over-engineered" our service based solution a bit](/documentation/tutorials/split-a-monolith/) (on purpose of course). We don't really need two backends services, so in this tutorial we will introduce our newly engineered solution and transition to it using Vamp blueprints and canary releasing methods. In this tutorial we will:

* Get some background and theory on merging services
* Prepare our blueprint
* Merge the blueprint with a running deployment
* Decommision parts of the deployment
* Answer the all important question _when would I use this?_

**Requirements:** Docker machine should have access to **at least 3GB memory**

## Some background and theory

What we are going to do is create a new blueprint that is completely valid by itself and merge it
with our already running deployment. This might sound strange at first, but it makes sense. Why? Merging will enable us to slowly move from the previous solution to the next solution. Once moved over, we can
remove any parts we no longer need, i.e. the former "over-engineered" topology.

![](/images/screens/v094/services_atob.png)

In the diagram above, this is visualized as follows:

1. We initiate a running deployment by deploying Blueprint A 
* We introduce a new service to the deployment by merging Blueprint B with the running deployment
* At this point, both blueprints are active allowing for a smooth transition. For example by canary release
* Once we are fully on running on Blueprint B, we can remove/decommission Blueprint A

## Prepare our blueprint

The below blueprint describes our more reasonable service topology. Again, this blueprint is completely
valid by itself. You could just deploy it somewhere separately and not merge it with our over-engineered
topology. Notice the following:

- There is only one backend cluster with one service
- There is no gateway specified. This is because we will use the gateway already present and configured in the running deployment. It would be perfectly correct to specify the old gateway, just not necesary.

```
name: sava:1.3
clusters:
  sava: # cluster 1
    services:
      breed:
        name: sava-frontend:1.3.0
        deployable: magneticio/sava-frontend:1.3.0
        ports:
          webport: 8080/http
        environment_variables:
          BACKEND: http://$backend.host:$backend.ports.webport/api/message
        dependencies:
          backend: sava-backend:1.3.0
      scale:
        cpu: 0.2
        memory: 64MB
        instances: 1
  backend: # cluster 2
    services:
      breed:
        name: sava-backend:1.3.0
        deployable: magneticio/sava-backend:1.3.0
        ports:
          webport: 8080/http
      scale:
        cpu: 0.2
        memory: 64MB
        instances: 1
```

## Merge the blueprint

We can merge our new blueprint with the running sava:1.2 deployment in the same way we approached the merge in the [run a canary release tutorial](/documentation/tutorials/run-a-canary-release/).  This will deploy the new sava:1.3. services alongside sava:1.2, without routing any traffic to them.  
You can do this using either the Vamp UI or API.

### Merge using the Vamp UI

1. Go to the **Blueprints** page and click **Add** (top right)
* Paste in the above blueprint and click **Save**. Vamp will store the blueprint and make it available for deployment 
* Open the action menu on the **sava:1.3** blueprint and select **Merge to** 
  ![](/images/screens/v094/tut4_merge.png)
* You'll be prompted to select the deployment you wish to merge the blueprint with - select **sava:1.2**
* Click **Merge** to deploy the services sava:1.3 and sava-backend:1.3 to the running sava:1.2 deployment.  

### Merge using the API

You can complete the same merge action with the Vamp API - remember to set the `Content-Type: application/x-yaml` for your requests:

1. To create the blueprint, `POST` the above blueprint YAML to `/api/v1/blueprints`  
* To merge the blueprint, `PUT` the below YAML to `/api/v1/deployments/sava:1.2`  

  ```
  name: sava:1.3
  ```

![](/images/screens/v094/tut4_merged_deployment.png)

So what happened here? Vamp worked out which parts of the blueprint were already in the deployment and which parts should be added. This is done based on naming. The sava cluster already existed, so Vamp simply added a service to it with 0% route weight. A cluster named "backend" didn't exist, so Vamp created it.

Notice we now have:

* Three backend clusters: two old ones (backend1 and backend2) and one from the new merge.
* Two services in the sava cluster: the old sava-frontend:1.2 and the new sava-frontend:1.3.  
  If you open the sava cluster **webport** you will see that the sava-frontend:1.2.0 route has a weight of 100% and the new new sava-frontend:1.3.0 route has a weight of 0%. Whenever Vamp merges a new service to an existing cluster it applies the default weight of 0%. This means no traffic will be routed to sava:1.3 yet.

![](/images/screens/v094/tut4_route_weights.png)



Now both blueprints are deployed, moving from the old to the new topology is just a question of “turning the weight dial”. You could do this in one go, or slowly adjust it. 

![](/images/screens/v094/tut4_sava_weight.png)

## Decomision parts of the deployment

Once we are fully running on sava:1.3, we can decommision the old, over-engineered sava:1.2.  We do this by updating the deployment again, this time to remove the sava:1.2 blueprint, effectively deleting all deployed sava:1.2 services.  

Note that we won't be able to remove any service unless its weight is set to 0%. If traffic is still being directed to a service requested for removal, Vamp will report an error.

### Delete using the Vamp UI

1. Go to the **Blueprints** page  
* Open the action menu on the **sava:1.2** blueprint and select **Remove from** 
  ![](/images/screens/v094/tut4_delete.png)
* You'll be prompted to select the deployment you wish to remove the blueprint from - select **sava:1.2**
* Click **Remove** to delete the services sava:1.2, sava-backend1:1.2 and sava-backend2:1.2 from the running sava:1.2 deployment.   
  
### Delete using the API

You can complete the same delete action with the Vamp API - remember to set the `Content-Type: application/x-yaml` for your requests:

1. To delete the sava:1.2 blueprint from the deployment, `DELETE` the below YAML to `/api/v1/deployments/sava:1.2`  

  ```
  name: sava:1.2
  ```

![](/images/screens/v094/tut4_after_delete.png)

Vamp will update the running deployment, removing all elements described in the sava:1.2 blueprint. This means that our running deployment **sava:1.2** now contains no sava:1.2 services - that's why including a version number in the name of a mutable deployment is a bad idea.

{'fraction_non_alphanumeric': 0.07716593245227607, 'fraction_numerical': 0.02459618208516887, 'mean_word_length': 3.672727272727273, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '409925', 'n_tokens_mistral': 4105, 'n_tokens_neox': 3879, 'n_words': 1871}