Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation updates #142

Merged
merged 9 commits into from
Jun 23, 2018
76 changes: 76 additions & 0 deletions packages/aws-cdk-docs/src/applets.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
International License (the "License"). You may not use this file except in compliance with the
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.

This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific language governing permissions and
limitations under the License.

.. _applets:

#######
Applets
#######

.. note:: Currently the |cdk| only supports applets published as JavaScript modules.

Applets are files in the YAML or JSON format that have the following root attribute,
where MODULE can represent
a local file, such as :code:`./my-module`,
a local dependency, such as :code:`my-dependency`,
or a global module, such as :code:`@aws-cdk/s3`
and CLASS is the name of a class exported by the module.

.. code:: js

applet: MODULE[:CLASS]

If CLASS is not specified, :code:`Applet` is used as the default class name.
Therefore, you need only refer to |cdk| construct libraries that export
an :code:`Applet` class by their library name.

The rest of the YAML file is applet-dependent.
The object is passed as :code:`props` when the applet object is instantiated
and added to an |cdk| app created by **cdk-applet-js**.

Use **cdk-applet-js** *applet* to run the applet, create an |cdk| app,
and use that with the |cdk| tools, as shown in the following example.

.. code-block:: sh

cdk --app "cdk-applet-js ./my-applet.yaml" synth

To make the applet file executable and use the host as a shebang
on Unix-based systems, such as Linux, MacOS, or Windows Bash shell,
create a script similar to the following.

.. code-block:: sh

#!/usr/bin/env cdk-applet-js

applet: aws-cdk-codebuild
source: arn:aws:codecommit:::my-repository
image: node:8.9.4
compute: large
build:
- npm install --unsafe-perm
- npm test
- npm pack --unsafe-perm

To execute the applet and synthesize an |CFN| template,
use the following command.

.. code-block:: sh

cdk synth --app "./build.yaml"

To avoid needing **--app** for every invocation,
add the following entry to *cdk.json*.

.. code-block:: json

{
"app": "./build.yaml"
}
84 changes: 84 additions & 0 deletions packages/aws-cdk-docs/src/apps.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
International License (the "License"). You may not use this file except in compliance with the
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.

This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific language governing permissions and
limitations under the License.

.. _apps:

####
Apps
####

The main artifact of an |cdk| program is called a *CDK App*.
This is an executable program that can be used to synthesize deployment artifacts
that can be deployed by supporting tools like the |toolkit|,
which are described in :doc:`tools`.

Tools interact with apps through the program's **argv**/**stdout** interface,
which can be easily implemented using the **App** class,
as shown in the following example.

.. code-block:: js

import { App } from '@aws-cdk/core'

const app = new App(process.argv); // input: ARGV

// <add stacks here>

process.stdout.write(app.run());

An |app-construct| is a collection of |stack| objects, as shown in the following
example.

.. code-block:: js

import { App } from '@aws-cdk/core'
import { MyStack } from './my-stack'

const app = new App(process.argv);

const dev = new MyStack(app, { name: 'Dev', region: 'us-west-2', dev: true })
const preProd = new MyStack(app, { name: 'PreProd', region: 'us-west-2', preProd: true })
const prod = [
new MyStack(app, { name: 'NAEast', region: 'us-east-1' }),
new MyStack(app, { name: 'NAWest', region: 'us-west-2' }),
new MyStack(app, { name: 'EU', region: 'eu-west-1', encryptedStorage: true })
]

new DeploymentPipeline(app, {
region: 'us-east-1',
strategy: DeploymentStrategy.Waved,
preProdStages: [ preProd ],
prodStages: prod
});

process.stdout.write(app.run());

Use the |toolkit| to list the stacks in this executable,
as shown in the following example.

.. code-block:: sh

cdk list
[
{ name: "Dev", region: "us-west-2" }
{ name: "PreProd", region: "us-west-2" },
{ name: "NAEast", region: "us-east-1" },
{ name: "NAWest", region: "us-west-2" },
{ name: "EU", region: "eu-west-1" },
{ name: "DeploymentPipeline", region: 'us-east-1' }
]

Or deploy one of the stacks,
as shown in the following example.

.. code-block:: sh

cdk deploy Dev
...
2 changes: 1 addition & 1 deletion packages/aws-cdk-docs/src/cloudformation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This section includes information about |cdk| features that most developers do n
Creating |l1| Constructs
========================

|l1| constructs are found in the :py:mod:`aws-cdk-resources` package. They map directly onto |cfn|
|l1| constructs are found in the :py:mod:`@aws-cdk/resources` package. They map directly onto |cfn|
resources.

.. important::
Expand Down
Loading