Commit 8fce0cb0 authored by Truc Nguyen's avatar Truc Nguyen Committed by GitHub

Merge pull request #103 from bonitasoft/merge_2.1_into_3.0

Merge 2.1 into 3.0
parents 47885be2 d4605cdb
......@@ -35,44 +35,6 @@ Further configuration instructions for **AWS single sign-on** can be found [on t
]
}
```
1. Create an IAM Policy to allow to describe DB instances and list tags (mandatory for dynamic inventory script).
- **Policy name**: RDSDescribeDBInstances
- **Policy document**:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1498730873000",
"Effect": "Allow",
"Action": [
"rds:DescribeDBInstances",
"rds:ListTagsForResource"
],
"Resource": [
"*"
]
}
]
}
```
1. Create an IAM Policy to grant full access to Amazon RDS on a specific region (eg. us-west-2). In order to do it you will need your account id (eg. 012345678901)
- **Policy name**: RDSFullAccess_us-west-2
- **Policy document**:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"rds:*"
],
"Effect": "Allow",
"Resource": "arn:aws:rds:us-west-2:012345678901:*"
}
]
}
```
1. Create an IAM Policy to give [PassRole](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) permission in order to be able to associate a specific role with the EC2 instances of a cluster.
- **Policy name**: IAMPassRole
- **Policy document**:
......
# How to deploy with an existing database
By default, BCD provisions a database Docker container while deploying your Bonita stack.
Alternatively, BCD also lets you connect your Bonita stack with an existing database server. The database vendor and version has to be supported by BCD though.
When the `bonita_db_host` variable is defined, BCD does not create a database container. Instead, BCD expects to connect to an existing database.
The following variables are to be set accordingly:
- `bonita_db_vendor` - Vendor name in [postgres, mysql, oracle].
- `bonita_db_host` - Host name or IP address (eg. `postgres.a1bac2defghi.us-west-2.rds.amazonaws.com`).
- `bonita_db_port` - Port number (eg. `5432`).
- `bonita_db_admin_user` - Name of an existing Administrator user (aka. "Master username"). This user must be granted permissions to create the Bonita and Business Data Model (BDM) databases.
- `bonita_db_admin_pass` - Password of the Administrator user.
Example with Amazon RDS <!--{.h2}-->
One typical use case is to deploy your Bonita stack using an [Amazon RDS](https://aws.amazon.com/rds/) instance.
1. Prior to creating your RDS instance, create and customize a [DB Parameter Group](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) in order to set database parameters for Bonita. Refer to Bonita documentation to check how to [Customize RDBMS to make it work with Bonita](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/database-configuration).
1. Create your RDS instance using the DB parameter group created previously. Make sure the assigned security group allows access to the DB instance.
Leave the **Database Name** field empty to not create a database. BCD will create required databases automatically.
1. Report connection information into your BCD scenario:
- `bonita_db_host` - DB instance endpoint (eg. `postgres.a1bac2defghi.us-west-2.rds.amazonaws.com`).
- `bonita_db_port` - Database Port (eg. `5432`).
- `bonita_db_admin_user` - Master Username.
- `bonita_db_admin_pass` - Master Password.
......@@ -2,9 +2,141 @@
The BCD controller can not only be run interactively, but also within standard Continuous Delivery servers such as [Jenkins automation server](https://jenkins.io/).
The `bonita-continuous-delivery_<version>.zip` archive provides a `jenkins-example` directory which contains a minimal working example of a Continuous Delivery platform with Jenkins and BCD.
This page describes 2 approaches to using BCD with Jenkins:
- First, a tutorial shows how to set up an **existing Jenkins** platform to start using BCD.
- Second, a **standalone example** lets you start a pre-configured Jenkins server with a BCD-aware Jenkins slave and ready-to-use Jenkins jobs.
## Integration tutorial
There are different ways to run BCD jobs with an existing Jenkins server.
Here is one recommended setup that requires a Docker host and little changes to your existing Jenkins instance.
With this setup, the Jenkins master, thanks to the [Jenkins Docker plugin](https://plugins.jenkins.io/docker-plugin), uses the **Docker host** to dynamically provision build agents. On the other hand, the Docker host needs to have the BCD controller image loaded and the `BCD_HOME` directory mounted.
![Bonita Continuous Delivery with Jenkins](images/bcd_jenkins.png "Bonita Continuous Delivery with Jenkins")
::: warning
This tutorial assumes you are already running a [Jenkins 2](https://jenkins.io/2.0/) instance and that you are familiar with Jenkins system administration.
:::
### Install Docker host
These steps are to be completed on the Docker host.
#### 1. Install Docker and enable remote access
The Docker host needs to run the Docker engine (Community or Enterprise Edition) and can be installed on any [supported platforms](https://docs.docker.com/install/#supported-platforms).
Besides, the Docker daemon must be accessible remotely on a TCP socket. The [Docker documentation](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-socket-option) describes how to enable the TCP socket.
It is also highly recommended to [protect the Docker daemon socket](https://docs.docker.com/engine/security/https/) by enabling the TLS protocol.
#### 2. Install BCD
BCD must be installed on the Docker host which acts here as a **control host**. The installation procedure is described in the [Getting started](getting_started.md) guide.
The Docker host should now have:
- the `bonitasoft/bcd-controller` Docker image loaded
- the `bonita-continuous-delivery_<version>` directory present
- optionally, the security files for BCD provisioning (SSH key files, AWS credentials)
### Configure Jenkins master
These steps are to be completed on the Jenkins master.
#### 1. Install required plugins
The Jenkins master must have the [Docker plugin](https://plugins.jenkins.io/docker-plugin) installed. The Docker plugin is a "Cloud" implementation that lets you add a new Cloud of type "Docker" on Jenkins master.
Additionally, it is recommended to use [Pipelines](https://jenkins.io/pipeline/getting-started-pipelines/) while using BCD with Jenkins. You can still use standard Jenkins "freestyle" jobs but pipelines are more designed for continuous delivery. Therefore this requires to install the [Pipeline plugin](https://plugins.jenkins.io/workflow-aggregator) (aka. `workflow-aggregator`).
This tutorial also provides an example pipeline which requires the [Pipeline Utility Steps](https://plugins.jenkins.io/pipeline-utility-steps), [Pipeline: GitHub Groovy Libraries](https://plugins.jenkins.io/pipeline-github-lib) and [AnsiColor](https://plugins.jenkins.io/ansicolor) plugins to be installed.
::: info
The [Jenkins plugins documentation](https://jenkins.io/doc/book/managing/plugins/#installing-a-plugin) describes different methods for installing plugins on master.
:::
#### 2. Add Docker Host credentials
As recommended previously, the Docker host should have TLS enabled. Therefore, the Docker host credentials must be added to Jenkins master.
Follow the [Jenkins credentials documentation](https://jenkins.io/doc/book/using/using-credentials/#adding-new-global-credentials) to add new **Docker Host Certificate Authentication** credentials. These credentials are required to declare a secured Docker cloud in the next step.
::: danger
If your Docker TCP socket is not secured, then you can skip this step. But bear in mind that exposing the Docker TCP socket without TLS is really **not safe**.
:::
#### 3. Add a new Cloud
This step instructs Jenkins master to add a new _Cloud_ of type Docker in order to provision build agents for BCD jobs.
Follow these steps to add a Docker cloud:
* Edit Jenkins system configuration (**Jenkins > Manage > System configuration**) and **Add a new cloud** of type _Docker_.
* Give it a **Name** and a **Docker Host URI** like `tcp://dockerhost:2376` (where `dockerhost` is the hostname or IP of the Docker host).
_It is conventional to use port `2376` when TLS is enabled, and port `2375` for un-encrypted communication with the Docker daemon._
* With a secured Docker TCP socket, select the **Server credentials** created previously. Otherwise, select _None_.
* Click on **Test Connection** to confirm your configuration is correct.
![Jenkins add Docker cloud](images/jenkins-add_cloud.png "Jenkins add Docker cloud")
#### 4. Add Docker template
A Docker template must be added to define how to start Jenkins build agents as BCD controller containers.
Click on **Add Docker template** to add a Docker template in the Docker cloud and filling in the fields as follows:
* **Labels**: `bcd`
* **Enabled**: `[checked]`
* **Name**: `bcd`
* **Docker Image**: `bonitasoft/bcd-controller:2.0.1` (where 2.0.1 is the version of BCD to use)
* **Volumes**:
```
/home/dockeruser/bonita-continuous-delivery_2.0.1:/home/bonita/bonita-continuous-delivery
/home/dockeruser/.ssh:/home/bonita/.ssh
```
* **Environment**: `ANSIBLE_FORCE_COLOR=true` (this forces colored output in BCD logs)
* **Remote File System Root**: `/home/bonita`
* **Connect method**: `Attach Docker container` - **User**: `bonita`
![Jenkins add Docker template](images/jenkins-add_docker_template.png "Jenkins add Docker template")
::: info
Jenkins is now ready to run BCD Pipelines. An example scripted pipeline is provided in the next section.
:::
### Create a Pipeline job
Create a **Pipeline** item with a `BCD_SCENARIO` String parameter which sets the BCD scenario path as an environment variable.
For instance, the `BCD_SCENARIO` parameter can be set to `scenarios/build_and_deploy.yml`.
Then here is an example pipeline script that builds a LivingApp repository and deploys its artifacts on an already runnning Bonita platform:
```
@Library('github.com/bonitasoft/bonita-jenkins-library@master') _
node('bcd') {
stage('Git Ckeckout') {
git url: 'https://github.com/bonitasoft/bonita-vacation-management-example', branch: 'master'
}
stage('build-bonita-app') {
bcd args: "livingapp build -p ${WORKSPACE} -e Qualification"
}
def jobBaseName = "${env.JOB_NAME}".split('/').last()
def artifacts_glob = "target/${jobBaseName}_*.zip"
stage('deploy-bonita-app') {
def zip_files = findFiles(glob: artifacts_glob)
bcd args: "livingapp deploy -p ${WORKSPACE}/${zip_files[0].path}"
}
stage('archive-artifacts') {
archiveArtifacts artifacts_glob
}
}
```
This pipeline uses a Jenkins shared library [hosted on GitHub](https://github.com/bonitasoft/bonita-jenkins-library).
This scripted pipeline can also be used in a [Jenkinsfile](https://jenkins.io/doc/book/pipeline/jenkinsfile/) and it can be checked into your LivingApp repository.
## Standalone example
The `bonita-continuous-delivery_<version>.zip` archive also provides a `jenkins-example` directory which contains a minimal working example of a Continuous Delivery platform with Jenkins and BCD. This example will start a pre-configured Jenkins server with a BCD-aware Jenkins slave and ready-to-use Jenkins jobs.
This example will start a pre-configured Jenkins server with a BCD-aware Jenkins slave and ready-to-use Jenkins jobs.
It is provided as a [Docker Compose](https://docs.docker.com/compose/) project.
Therefore you should have **Docker and Docker Compose** installed on the target host to run this example.
......@@ -16,7 +148,7 @@ In this example, a Jenkins slave is created from a Docker image which extends th
This allows you to easily re-use parts of this example in your own Jenkins instance.
:::
## Step-by-step run guide
### Step-by-step run guide
Here is a step-by-step guide to run this example.
The following commands are to be executed on the target host where Jenkins is to be installed.
......@@ -45,7 +177,7 @@ You can now log-in to Jenkins using one of the pre-configured users:
**Important Note**: Prepare your BCD scenario and dependencies as usual before using the pre-configured Jenkins jobs.
:::
## Pre-configured Jenkins jobs
### Pre-configured Jenkins jobs
Once authenticated to Jenkins you can now launch pre-configured jobs.
This example project provides the following jobs:
......
......@@ -45,7 +45,6 @@ The following variables are specific to AWS deployments ie. when `bcd_provider`
| ec2_discovery_iam_role | N | - | Name of the IAM role to attach to EC2 instances to allow Hazelcast EC2 auto-discovery. This is MANDATORY when deploying a Bonita cluster on AWS with BCD. | ClusterBCD |
| ec2_vpc_destination_variable | N | - | Type of network address the EC2 dynamic inventory script should use. For instance, if you are running the BCD controller **from outside EC2**, the `vpc_destination_variable` parameter should be set to `ip_address`. If you are running the BCD controller **from within EC2**, the `vpc_destination_variable` parameter should be set to `private_ip_address`. | ip_address |
| boto_path | N | ~/.boto | Path to the Boto file with the AWS credentials. | ~/.boto |
| rds | N | false | Use an existing AWS RDS database instance. By default this parameter is set to `false` to create an EC2 instance for Bonita database. | true |
| aws_ami | Y | - | Common AMI for all EC2 instances. Depends on AWS region. Should be a [supported operating system](requirements-and-compatibility.md) and ebs-ssd type. | ami-fc4f5e85 |
| aws_database_instance_type | Y | - | EC2 instance type for the database instance. | t2.micro |
| aws_bonita_instance_type | Y | - | EC2 instance type for the Bonita instances. | t2.micro |
......
* [Release notes](release_notes.md)
* [Requirements and compatibility](requirements-and-compatibility.md)
* [Getting started](getting_started.md)
* [Upgrade BCD](upgrade_bcd.md)
* [BCD services and scenarios](_bcd_services_and_scenarios.md)
* [Controller Docker image](bcd_controller.md)
* [Command-line interface](bcd_cli.md)
......@@ -12,6 +13,7 @@
* [Assume IAM role within AWS Organizations](aws_organizations.md)
* [Configure Microsoft Azure for BCD](azure-prerequisites.md)
* [Deploy with a static inventory](deploy_with_static_inventory.md)
* [Deploy with an existing database](deploy-with-existing-database.md)
* [Customize the Bonita container](_custom_init.md)
* [Using initialization scripts](custom_init.md)
* [Configuring REST API authorization](how_to_configure_rest_api_authorization.md)
......
# Migrate from an earlier version of BCD
## Overview
This page explains how to upgrade your version of BCD.
Each of the versions follow the MAJOR.MINOR.PATCH format.
We have split this documentation in order to describe the differences between upgrades.
We will focus on :
- scenarios : indeed you may want to keep your existing scenarios. It will allow you to recreate the same kind of stack or manipulate an existing one (deploy, undeploy, destroy).
- Terraform metadata : "Terraform must store state about your managed infrastructure and configuration. This state is used by Terraform to map real world resources to your configuration, keep track of metadata, and to improve performance for large infrastructures." [https://www.terraform.io/docs/state/](https://www.terraform.io/docs/state/).
So if you want to be able to manage an existing stack (i.e. a stack already deployed from a previous version of BCD) you will need to copy paste this state.
- bcd controller
- Vagrant : this part applies only if you use Vagrant virtual machines.
- Living Application repositories : this part applies only for migrations from a 2.0.x
## How it works
### From a 1.0.x towards a ${varVersion}.y
Please follow the previous documentation describing the [upgrade from 1.0 toward 2.1](https://documentation.bonitasoft.com/bcd/2.1/upgrade_bcd). Then follow the instructions in the next section.
### From a 2.1.x towards a ${varVersion}.y
#### Scenarios
You will first need to copy the files
```
cp bonita-continuous-delivery_2.1.0/scenarios/*.yml bonita-continuous-delivery_${varVersion}.0/scenarios/
```
Then you will have to check `Breaking changes` section into the [release notes](release_notes.md). Indeed you will have to had the new parameters `bcd_registry_user` and `bcd_registry_password` in order to retrieves the BCD dependencies from a private docker registry.
#### Terraform
Copy the directory corresponding to your stack.
```
cp -r bonita-continuous-delivery_2.1.0/terraform/your_stack_name bonita-continuous-delivery_${varVersion}.0/terraform/
```
#### BCD controller
As is described into the "Installation guide" from the [Getting started](getting_started.md) you will need to load the last version of `bcd-controller_<version>.tar.zip Docker image.
You can also directly use the private Docker registry to retrive the latest image.
```
docker login quay.io
Username: myusername
Password: mypassword
docker pull quay.io/bonitasoft/bcd-controller
```
#### Vagrant
As the controller access to them over the network it's not necessary to move them on the filesystem.
But if you plan to cleanup the old directory you can moved the vagrant data located inside `1-machine` or `2-machines` directories by copying the `.vagrant` subdirectories.
```
cp -r bonita-continuous-delivery_2.1.0/vagrant/1-machine/.vagrant bonita-continuous-delivery_${varVersion}.0/vagrant/1-machine/
cp -r bonita-continuous-delivery_2.1.0/vagrant/2-machines/.vagrant bonita-continuous-delivery_${varVersion}.0/vagrant/2-machines/
```
#### Living Application repositories
Move the directories where you have cloned your repositories.
For example :
```
cp -r bonita-continuous-delivery_2.1.0/bonita-vacation-management-example bonita-continuous-delivery_${varVersion}.0/bonita-vacation-management-example
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment