Skip to content

Commit 9159ba2

Browse files
author
awstools
committed
feat(client-appconfig): AWS AppConfig now supports dynamic parameters, which enhance the functionality of AppConfig Extensions by allowing you to provide parameter values to your Extensions at the time you deploy your configuration.
1 parent e9ce4e8 commit 9159ba2

16 files changed

+653
-182
lines changed

‎clients/client-appconfig/README.md

Lines changed: 134 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -6,50 +6,154 @@
66

77
AWS SDK for JavaScript AppConfig Client for Node.js, Browser and React Native.
88

9-
<p>Use AppConfig, a capability of Amazon Web Services Systems Manager, to create, manage, and quickly
10-
deploy application configurations. AppConfig supports controlled deployments to
11-
applications of any size and includes built-in validation checks and monitoring. You can
12-
use AppConfig with applications hosted on Amazon EC2 instances, Lambda, containers,
13-
mobile applications, or IoT devices.</p>
14-
<p>To prevent errors when deploying application configurations, especially for production
15-
systems where a simple typo could cause an unexpected outage, AppConfig includes
16-
validators. A validator provides a syntactic or semantic check to ensure that the
17-
configuration you want to deploy works as intended. To validate your application
18-
configuration data, you provide a schema or an Amazon Web Services Lambda function that runs against
19-
the configuration. The configuration deployment or update can only proceed when the
20-
configuration data is valid.</p>
21-
<p>During a configuration deployment, AppConfig monitors the application to
22-
ensure that the deployment is successful. If the system encounters an error, AppConfig rolls back the change to minimize impact for your application users. You can
23-
configure a deployment strategy for each application or environment that includes
24-
deployment criteria, including velocity, bake time, and alarms to monitor. Similar to error
25-
monitoring, if a deployment triggers an alarm, AppConfig automatically rolls back
26-
to the previous version. </p>
27-
<p>AppConfig supports multiple use cases. Here are some examples:</p>
9+
<p>AppConfig feature flags and dynamic configurations help software builders
10+
quickly and securely adjust application behavior in production environments without full
11+
code deployments. AppConfig speeds up software release frequency, improves
12+
application resiliency, and helps you address emergent issues more quickly. With feature
13+
flags, you can gradually release new capabilities to users and measure the impact of those
14+
changes before fully deploying the new capabilities to all users. With operational flags
15+
and dynamic configurations, you can update block lists, allow lists, throttling limits,
16+
logging verbosity, and perform other operational tuning to quickly respond to issues in
17+
production environments.</p>
18+
<note>
19+
<p>AppConfig is a capability of Amazon Web Services Systems Manager.</p>
20+
</note>
21+
<p>Despite the fact that application configuration content can vary greatly from
22+
application to application, AppConfig supports the following use cases, which
23+
cover a broad spectrum of customer needs:</p>
2824
<ul>
2925
<li>
3026
<p>
31-
<b>Feature flags</b>: Use AppConfig to turn on
32-
new features that require a timely deployment, such as a product launch or
33-
announcement. </p>
27+
<b>Feature flags and toggles</b> - Safely release new
28+
capabilities to your customers in a controlled environment. Instantly roll back
29+
changes if you experience a problem.</p>
3430
</li>
3531
<li>
3632
<p>
37-
<b>Application tuning</b>: Use AppConfig to
38-
carefully introduce changes to your application that can only be tested with
39-
production traffic.</p>
33+
<b>Application tuning</b> - Carefully introduce
34+
application changes while testing the impact of those changes with users in
35+
production environments.</p>
4036
</li>
4137
<li>
4238
<p>
43-
<b>Allow list</b>: Use AppConfig to allow
44-
premium subscribers to access paid content. </p>
39+
<b>Allow list or block list</b> - Control access to
40+
premium features or instantly block specific users without deploying new code.
41+
</p>
4542
</li>
4643
<li>
4744
<p>
48-
<b>Operational issues</b>: Use AppConfig to
49-
reduce stress on your application when a dependency or other external factor impacts
50-
the system.</p>
45+
<b>Centralized configuration storage</b> - Keep your
46+
configuration data organized and consistent across all of your workloads. You can use
47+
AppConfig to deploy configuration data stored in the AppConfig
48+
hosted configuration store, Secrets Manager, Systems Manager, Parameter
49+
Store, or Amazon S3.</p>
5150
</li>
5251
</ul>
52+
<p>
53+
<b>How AppConfig works</b>
54+
</p>
55+
<p>This section provides a high-level description of how AppConfig works and how
56+
you get started.</p>
57+
<dl>
58+
<dt>1. Identify configuration values in code you want to manage in the cloud</dt>
59+
<dd>
60+
<p>Before you start creating AppConfig artifacts, we recommend you
61+
identify configuration data in your code that you want to dynamically manage using
62+
AppConfig. Good examples include feature flags or toggles, allow and
63+
block lists, logging verbosity, service limits, and throttling rules, to name a
64+
few.</p>
65+
<p>If your configuration data already exists in the cloud, you can take advantage
66+
of AppConfig validation, deployment, and extension features to further
67+
streamline configuration data management.</p>
68+
</dd>
69+
<dt>2. Create an application namespace</dt>
70+
<dd>
71+
<p>To create a namespace, you create an AppConfig artifact called an
72+
application. An application is simply an organizational construct like a
73+
folder.</p>
74+
</dd>
75+
<dt>3. Create environments</dt>
76+
<dd>
77+
<p>For each AppConfig application, you define one or more environments.
78+
An environment is a logical grouping of targets, such as applications in a
79+
<code>Beta</code> or <code>Production</code> environment, Lambda functions,
80+
or containers. You can also define environments for application subcomponents,
81+
such as the <code>Web</code>, <code>Mobile</code>, and
82+
<code>Back-end</code>.</p>
83+
<p>You can configure Amazon CloudWatch alarms for each environment. The system monitors
84+
alarms during a configuration deployment. If an alarm is triggered, the system
85+
rolls back the configuration.</p>
86+
</dd>
87+
<dt>4. Create a configuration profile</dt>
88+
<dd>
89+
<p>A configuration profile includes, among other things, a URI that enables
90+
AppConfig to locate your configuration data in its stored location
91+
and a profile type. AppConfig supports two configuration profile types:
92+
feature flags and freeform configurations. Feature flag configuration profiles
93+
store their data in the AppConfig hosted configuration store and the URI
94+
is simply <code>hosted</code>. For freeform configuration profiles, you can store
95+
your data in the AppConfig hosted configuration store or any Amazon Web Services
96+
service that integrates with AppConfig, as described in <a href="http://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-free-form-configurations-creating.html">Creating
97+
a free form configuration profile</a> in the the <i>AppConfig User Guide</i>.</p>
98+
<p>A configuration profile can also include optional validators to ensure your
99+
configuration data is syntactically and semantically correct. AppConfig
100+
performs a check using the validators when you start a deployment. If any errors
101+
are detected, the deployment rolls back to the previous configuration data.</p>
102+
</dd>
103+
<dt>5. Deploy configuration data</dt>
104+
<dd>
105+
<p>When you create a new deployment, you specify the following:</p>
106+
<ul>
107+
<li>
108+
<p>An application ID</p>
109+
</li>
110+
<li>
111+
<p>A configuration profile ID</p>
112+
</li>
113+
<li>
114+
<p>A configuration version</p>
115+
</li>
116+
<li>
117+
<p>An environment ID where you want to deploy the configuration data</p>
118+
</li>
119+
<li>
120+
<p>A deployment strategy ID that defines how fast you want the changes to
121+
take effect</p>
122+
</li>
123+
</ul>
124+
<p>When you call the <a href="https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_StartDeployment.html">StartDeployment</a> API action, AppConfig performs the following
125+
tasks:</p>
126+
<ol>
127+
<li>
128+
<p>Retrieves the configuration data from the underlying data store by using
129+
the location URI in the configuration profile.</p>
130+
</li>
131+
<li>
132+
<p>Verifies the configuration data is syntactically and semantically correct
133+
by using the validators you specified when you created your configuration
134+
profile.</p>
135+
</li>
136+
<li>
137+
<p>Caches a copy of the data so it is ready to be retrieved by your
138+
application. This cached copy is called the <i>deployed
139+
data</i>.</p>
140+
</li>
141+
</ol>
142+
</dd>
143+
<dt>6. Retrieve the configuration</dt>
144+
<dd>
145+
<p>You can configure AppConfig Agent as a local host and have the agent
146+
poll AppConfig for configuration updates. The agent calls the <a href="https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_StartConfigurationSession.html">StartConfigurationSession</a> and <a href="https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_GetLatestConfiguration.html">GetLatestConfiguration</a> API actions and caches your configuration data
147+
locally. To retrieve the data, your application makes an HTTP call to the
148+
localhost server. AppConfig Agent supports several use cases, as
149+
described in <a href="http://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-retrieving-simplified-methods.html">Simplified
150+
retrieval methods</a> in the the <i>AppConfig User
151+
Guide</i>.</p>
152+
<p>If AppConfig Agent isn't supported for your use case, you can
153+
configure your application to poll AppConfig for configuration updates
154+
by directly calling the <a href="https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_StartConfigurationSession.html">StartConfigurationSession</a> and <a href="https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_GetLatestConfiguration.html">GetLatestConfiguration</a> API actions. </p>
155+
</dd>
156+
</dl>
53157
<p>This reference is intended to be used with the <a href="http://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html">AppConfig User
54158
Guide</a>.</p>
55159

0 commit comments

Comments
 (0)