forked from cloudfoundry/docs-dev-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrevisions.html.md.erb
172 lines (115 loc) · 5.34 KB
/
revisions.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
---
title: App Revisions
owner: CAPI
---
This topic describes app revisions and provides procedures for working with them.
For additional information, see [Revisions](http://v3-apidocs.cloudfoundry.org/version/release-candidate/#revisions) in the Cloud Foundry API (CAPI) documentation.
<p class="note"><strong>Note:</strong> CAPI v3 is the recommended API version for revisions. While revisions work with CAPI v2, there are several inconsistencies. For example, revision descriptions for apps with multiple processes may be inaccurate because CAPI v2 does not support apps with multiple processes. Additionally, pushing an app for the first time with revisions in CAPI v2 creates two revisions.</p>
<p class="note"><strong>Note:</strong> The App Revisions API is experimental, and future releases may have breaking changes.</p>
## <a id="overview"></a> Overview
A revision represents code and configuration used by an app at a specific time. It is a CAPI object that can contain references to a droplet, custom start command, and environment variables. The most recent revision for a running app represents code and configuration currently running in <%= vars.platform_name %>.
Some use cases for revisions include:
* **Viewing revisions for an app:** This can help you understand how your app has changed over time.
* **Rolling back to a previous revision:** This allows you to deploy a version of the app that you had running previously without needing to track that previous state yourself or have multiple apps running. When you create a deployment and reference a revision, the revision deploys as the current version of your app.
### <a id="events"></a> Events that Trigger Revisions
Revisions are generated automatically through these events:
* A new droplet is created for an app.
* An app's environment variables are changed.
* The custom start command for an app is added or changed.
* An app rolls back to a prior revision.
By default, CAPI retains a maximum of 100 revisions per app.
### <a id="revision-description"></a> Revision Descriptions
Each revision includes a description of what changed in your app at the time the revision was created. The description includes one or more of these descriptions:
* `Process type removed`
* `New process type added`
* `Rolled back to revision X`
* `Custom start command removed`
* `Custom start command updated`
* `Custom start command added`
* `New environment variables deployed`
* `New droplet deployed`
### <a id="droplets"></a> Droplet Storage Considerations
By default, <%= vars.platform_name %> retains the five most recent staged droplets in its droplets bucket. This means that you can roll back to revisions as long as they are using one of those five droplets. Not all revisions include a change in droplet.
<% if vars.platform_code.include? "CF" %>
Operators can configure <%= vars.platform_name %> to retain more droplets if necessary using the <%= vars.droplet_config %>
<% end %>
## <a id="view"></a> View Revisions
This section describes how to use CAPI endpoints for viewing revisions.
### <a id="list"></a> List Revisions for an App
To list revisions for an app:
1. Retrieve the GUID of the app by running:
```
cf app APP-NAME --guid
```
Where `APP-NAME` is the name of your app.
1. Run:
```
cf curl /v3/apps/GUID/revisions
```
Where `GUID` is the GUID you retrieved in the previous step.
### <a id="list-deployed"></a> List Deployed Revisions for an App
Deployed revisions are revisions linked to started processes in an app. To list deployed revisions:
1. Retrieve the GUID of the app by running:
```
cf app APP-NAME --guid
```
Where `APP-NAME` is the name of your app.
1. Run:
```
cf curl /v3/apps/GUID/revisions/deployed
```
Where `GUID` is the GUID you retrieved in the previous step.
### <a id="get"></a> Retrieve a Revision
To retrieve a revision:
1. Run:
```
cf curl /v3/revisions/GUID
```
Where `GUID` is the GUID of the revision.
## <a id="push-app"></a> Roll Back to a Previous Revision
To roll back to a previous revision:
1. Retrieve the GUID of the app by running:
```
cf app APP-NAME --guid
```
Where `APP-NAME` is the name of your app.
1. Retrieve the GUID of the revision. For more information, see [Retrieve a Revision](#get).
1. Create a deployment using CAPI by running:
```
cf curl v3/deployments \
-X POST \
-d '{
"revision": {
"guid": "REVISION-GUID"
},
"relationships": {
"app": {
"data": {
"guid": "APP-GUID"
}
}
}
}'
```
Where:
* `REVISION-GUID` is the GUID of the revision.
* `APP-GUID` is the GUID of the app.
## <a id="metadata"></a> Add Metadata to a Revision
<% if vars.platform_code.include? "CF" %>
To add metadata to a revision, see [Add Metadata to an Object](../adminguide/metadata.html).
<% else %>
To add metadata to a revision, see [Add Metadata to an Object](https://docs.cloudfoundry.org/adminguide/metadata.html).
<% end %>
## <a id="disable"></a> Disable Revisions for an App
CAPI enables app revisions by default. To disable revisions for an app, you must manually turn them off.
To disable revisions for an app:
1. Retrieve the GUID of the app by running:
```
cf app APP-NAME --guid
```
Where `APP-NAME` is the name of your app.
1. Run:
```
cf curl /v3/apps/GUID/features/revisions -X PATCH -d '{ "enabled": false }'
```
Where `GUID` is the GUID you retrieved in the previous step.