/
index.html.md.erb
224 lines (155 loc) · 8.46 KB
/
index.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
---
title: BOSH Backup and Restore (BBR)
owner: BBR
---
This guide documents BOSH Backup and Restore (BBR), a framework for backing up and restoring BOSH
deployments and BOSH Directors.
BBR orchestrates triggering the backup or restore process on the BOSH deployment or BOSH Director,
and transfers the backup artifacts to and from the BOSH deployment or BOSH Director.
Cloud Foundry recommends that you frequently back up your deployment using BBR, especially before
upgrading a deployment.
For more information about installing and using BBR, see the
[Installing BOSH Backup and Restore](installing.html),
[Backing up with BOSH Backup and Restore](backup.html),
and [Restoring with BOSH Backup and Restore](restore.html) topics.
Information for release authors and developers is also available in the
[BOSH Backup and Restore Developer's Guide](bbr-devguide.html).
For more information about backing up and restoring cf-deployment with BBR, see
[Configuring Cloud Foundry for BOSH Backup and Restore](cf-backup.html).
## <a id='supported'></a>Supported components
BBR is a binary that can back up and restore BOSH deployments and BOSH Directors.
BBR requires that the backup targets supply scripts that implement the backup and restore functions.
BBR is not dependent on a particular version of BOSH.
However, a BOSH deployment must have its backup and restore [scripts](#contract) packaged in the
releases to be backed up and restored with BBR. For more information, consult the documentation for
the deployment.
<b>You can currently back up and restore the following BOSH deployments with BBR:</b>
<%= vars.bbr_ert %>
1. The BOSH Director, including CredHub, with either Basic Auth or Client/Client-Secret UAA
authentication
1. Cloud Foundry with specific [configuration](cf-backup.html)
## <a id='contract'></a>Contract
BBR sets out a contract with BOSH release authors to call designated backup and restore scripts in a
specific order.
This approach has the following advantages:
* The deployment itself encapsulates the knowledge of how to back up and restore the deployment.
* Because the release author is responsible for writing and maintaining scripts, scripts
can change as the deployment changes and do not get out of sync.
### Backup scripts
1. **pre-backup-lock**: The pre-backup lock script locks the job so backups are consistent across the
cluster.
1. **backup**: The backup script backs up the release.
1. **post-backup-unlock**: The post-backup unlock script unlocks the job after the backup is complete.
### Restore scripts
1. **pre-restore-lock**: The pre-restore-lock script locks the job so the restore is consistent
across the cluster.
1. **restore**: The restore script restores the release.
1. **post-restore-unlock**: The post-restore-unlock script unlocks the job after the restore is
complete.
## <a id='workflow'></a>What happens when you run a BBR backup?
**Prerequisite:** The operator has [installed BBR](installing.html).
When a BBR `backup` command is run the following things happen:
BBR connects to instances in the deployment/director that was specified in the BBR command invocation.
Using these connections, BBR gathers information about which scripts it should run for each stage in
the backup.
BBR then runs the `pre-backup-lock`, `backup`, and `post-backup-unlock` scripts in stages.
Scripts in the same stage all finish before the next stage starts.
For instance, BBR triggers and waits for completion of all `pre-backup-lock` scripts before it
triggers any `backup` scripts.
Scripts within the `backup` stage can happen in any order.
A release author can configure ordering for scripts in in the `locking` and `unlocking` stages, but
any scripts that are unconstrained by that ordering can also happen in any order within their stage.
BBR drains and tars the backup artifacts to the jumpbox from where the operator can transfer the
resulting artifact to storage and use it to restore the BOSH deployment or BOSH Director.
The following diagram shows a sample backup flow.
<%= image_tag("backup-flow.png", :alt => "This diagram is described in the steps immediately below.") %>
In the diagram above:
1. An operator runs `bbr backup pcf-deployment` on the jumpbox.
1. BBR calls the following backup scripts on the deployment:
* `backup-lock`
* `backup`
* `backup-unlock`
1. BBR transfers the backup artifacts from the deployment to the jumpbox.
1. BBR transfers the backup artifacts from the jumpbox to a secondary backup store that is outside of
the network or availability zone (AZ).
## <a id='workflow-restore'></a>What happens when you run a BBR restore?
*Prerequisite:* You have available on the jumpbox an artifact produced by a BBR `backup` of your
deployment or director.
When a BBR `restore` command is run for that artifact the following things happen:
BBR connects to instances in the deployment/director that was specified in the command invocation.
Using these connections, BBR gathers information about which scripts it should run for each stage in
the restore.
BBR uploads the each part of the artifact to the instance it belongs to.
BBR then runs the `pre-restore-lock`, `restore`, and `post-restore-unlock` scripts in stages.
Scripts in the same stage all finish before the next stage starts.
For instance, BBR triggers and waits for completion of all `pre-restore-lock` scripts before it
triggers any `restore` scripts.
Scripts within the `restore` stage can happen in any order.
A release author can configure ordering for scripts in in the `locking` and `unlocking` stages, but
any scripts that are unconstrained by that ordering can also happen in any order within their stage.
## <a id='syntax'></a>Syntax
This section provides syntax information for the BBR binary.
For detailed procedures on how to use BBR to back up and restore a BOSH Director or BOSH deployment,
see the [Backing up with BOSH Backup and Restore](backup.html) and
[Restoring with BOSH Backup and Restore](restore.html) topics.
The syntax for the BBR binary is:
```bash
bbr [command] [arguments...] [subcommand]
```
The options for `[command]` are:
* `deployment`: Specifies that the target of BBR is a BOSH deployment
* `director`: Specifies that the target of BBR is a BOSH Director
* `help`: Prints help text
* `version`: Prints the version of the `bbr` binary
The `[arguments]` are specific to the command.
### BOSH Director
The arguments to specify when running BBR for a BOSH Director are:
```bash
$ bbr director \
--debug (OPTIONAL) \
--private-key-path PATH_TO_PRIVATE_KEY \
--username USER_NAME \
--host HOST \
SUB-COMMAND [--artifact-path PATH_TO_ARTIFACT]
```
The parameters are:
* `--debug`: This is an optional flag to display debug output.
* `--private-key-path`: This is the path to the SSH private key used to connect to the BOSH Director.
* `--username`: This is the SSH username of the BOSH Director.
* `--host`: This is the address of the BOSH Director with an optional port that defaults to 22.
If the BOSH Director is public, this is a URL, such as `https://my-bosh.xxx.cf-app.com`.
Otherwise, this is the BOSH Director IP address.
* `--artifact-path`: This is the path to the BOSH Director backup artifact you want to backup to or
restore from.
### BOSH deployment
The arguments to specify when running BBR for a BOSH deployment are:
```bash
$ BOSH_CLIENT_SECRET=BOSH_CLIENT_SECRET \
bbr deployment \
--debug (OPTIONAL)
--target BOSH_TARGET \
--username BOSH_CLIENT \
--deployment DEPLOYMENT_NAME \
--ca-cert PATH_TO_BOSH_CA_CERTIFICATE \
SUB-COMMAND [--artifact-path PATH_TO_ARTIFACT]
```
The arguments are:
* `--debug`: This is an optional flag to display debug output.
* `BOSH_CLIENT`, `BOSH_CLIENT_SECRET`: If you have a BOSH Director with User Account and
Authentication (UAA) as the authentication provider, use a UAA client as the username and a UAA
client secret as the password.
If you have a BOSH Director with basic authentication configured, use your username and password.
* `--target`: This is the FQDN or IP address of your BOSH Director.
* `--deployment`: This is the name of the deployment you want to back up. For a list of deployments,
run `bosh deployments`.
* `--ca-cert`: This is the path to the BOSH Director's Certificate Authority (CA) certificate if the
certificate is not verifiable by the local machine's certificate chain.
* `--artifact-path`: This is the path to the BOSH deployment backup artifact you want to backup to or
restore from.
### Subcommands
BBR supports five subcommands:
* `backup`
* `restore`
* `pre-backup-check`
* `backup-cleanup`
* `restore-cleanup`