Merge pull request #11 from waterbear-cloud/snstopic

Snstopic

CHANGELOG.md

@@ -1,7 +1,7 @@
 Changelog for aim
 =================
 
-1.1.1 (unreleased)
+2.0.1 (unreleased)
 ------------------
 
 ### Added
@@ -13,6 +13,11 @@ Changelog for aim
 
 - Added Account initialization to 'aim init project'.
 
+### Changed
+
+ - AIM references have a new format! It's simpler and more consistent.
+   Every ref now starts with ``aim.ref ``.
+
 
 1.1.0 (2019-07-24)
 ------------------

docs/aim-config.rst

@@ -183,35 +183,40 @@ References and Substitutions
 Some values can be special references. These will allow you to reference other values in
 your AIM Configuration.
 
- * ``netenv.ref``: NetworkEnvironment reference
+ * ``aim.ref netenv``: NetworkEnvironment reference
 
- * ``resource.ref``: Resource reference
+ * ``aim.ref resource``: Resource reference
 
- * ``config.ref``: Config reference
+ * ``aim.ref accounts``: Account reference
 
- * ``function.ref``: Function reference
+ * ``aim.ref function``: Function reference
+
+ * ``aim.ref service``: Service reference
 
 References are in the format:
 
 ``type.ref name.seperated.by.dots``
 
-In addition, the ``aim.sub`` will indicate a substitution.
+In addition, the ``aim.sub`` string indicates a substitution.
 
-netenv.ref
-----------
+aim.ref netenv
+--------------
 
-NetworkEnvironment references refer to values in a NetworkEnvironment.
+To refer to a value in a NetworkEnvironment use an ``aim.ref netenv`` reference. For example:
 
-The first part of the reference will be a filename of a file in the NetworkEnvironments directory.
+``aim.ref netenv.my-aim-example.network.vpc.security_groups.app.lb.id``
 
-The second part can be either ``applications`` or ``network``.
+After ``aim.ref netenv`` should be a part which matches the filename of a file (without the .yaml or .yml extension)
+in the NetworkEnvironments directory.
 
-The following parts will then continue to walk down the tree by key name. The final part will
-be the name of a field. This final part can sometimes be a field name that you don't supply
-in your configuration, and is instead can be generated by the AIM Engine after it has provisioned
-the resource in AWS.
+The next part will start to walk down the YAML tree in the specified file. You can
+either refer to a part in the ``applications`` or ``network`` section.
 
-An example where a ``netenv.ref`` refers to the id of a SecurityGroup:
+Keep walking down the tree, until you reach the name of a field. This final part is sometimes
+a field name that you don't supply in your configuration, and is instead can be generated
+by the AIM Engine after it has provisioned the resource in AWS.
+
+An example where a ``aim.ref netenv`` refers to the id of a SecurityGroup:
 
 .. code-block:: yaml
 
@@ -226,13 +231,13 @@ An example where a ``netenv.ref`` refers to the id of a SecurityGroup:
                             - from_port: 80
                             name: HTTP
                             protocol: tcp
-                            source_security_group_id: netenv.ref my-aim-example.network.vpc.security_groups.app.lb.id
+                            source_security_group_id: aim.ref netenv.my-aim-example.network.vpc.security_groups.app.lb.id
 
 You can refer to an S3 Bucket and it will return the ARN of the bucket:
 
 .. code-block:: yaml
 
-    artifacts_bucket: netenv.ref my-aim-example.applications.app.groups.cicd.resources.cpbd_s3
+    artifacts_bucket: aim.ref netenv.my-aim-example.applications.app.groups.cicd.resources.cpbd_s3
 
 SSL Certificates can be added to a load balancer. If a reference needs to look-up the name or id of an AWS
 Resource, it needs to first be provisioned, the ``order`` field controls the order in which resources
@@ -263,13 +268,19 @@ and configured with the ACM cert:
                             - port: 443
                                 protocol: HTTPS
                                 ssl_certificates:
-                                - netenv.ref my-aim-example.applications.app.groups.site.resources.cert.arn
+                                - aim.ref netenv.my-aim-example.applications.app.groups.site.resources.cert.arn
 
 
-resource.ref
------------
+aim.ref resource
+----------------
 
-If you need to refer to a global resource created in the Resources directory, use a ``resource.ref``.
+To refer to a global resource created in the Resources directory, use an ``aim.ref resource``. For example:
+
+``aim.ref resource.route53.example.id``
+
+After the ``aim.ref resource`` the next part should matche the filename of a file
+(without the .yaml or .yml extension)  in the Resources directory.
+Subsequent parts will walk down the YAML in that file.
 
 In the example below, the ``hosted_zone_id`` of a Route53 record is looked up.
 
@@ -283,43 +294,63 @@ In the example below, the ``hosted_zone_id`` of a Route53 record is looked up.
                 site:
                     alb:
                         dns:
-                        - hosted_zone_id: resource.ref route53.example.id
+                        - hosted_zone_id: aim.ref resource.route53.example.id
 
     # Resources/Route53.yaml
 
     hosted_zones:
     example:
         enabled: true
         domain_name: example.com
-        account: config.ref accounts.prod
+        account: aim.ref accounts.prod
 
 
-config.ref
-----------
+aim.ref accounts
+----------------
+
+To refer to an AWS Account in the Accounts directory, use ``aim.ref``. For example:
 
-If you want to refer to an AWS Account in the Accounts directory, use ``config.ref``.
+``aim.ref accounts.dev``
+
+Account references should matches the filename of a file (without the .yaml or .yml extension)
+in the Accounts directory.
 
 These are useful to override in the environments section in a NetworkEnvironment file
-to control which account and environment should be deployed to:
+to control which account an environment should be deployed to:
 
 .. code-block:: yaml
 
     environments:
         dev:
             network:
-                aws_account: config.ref accounts.dev
+                aws_account: aim.ref accounts.dev
 
-function.ref
-------------
+aim.ref function
+----------------
+
+A reference dynamically resolved at runtime. For example:
+
+``aim.ref function.aws.ec2.ami.latest.amazon-linux-2``
 
-A reference dynamically resolved at runtime. Currently can only look-up AMI IDs.
-Can be either ``aws.ec2.ami.latest.amazon-linux-2`` or ``aws.ec2.ami.latest.amazon-linux``.
+Currently can only look-up AMI IDs. Can be either ``aws.ec2.ami.latest.amazon-linux-2``
+or ``aws.ec2.ami.latest.amazon-linux``.
 
 .. code-block:: yaml
 
     web:
         type: ASG
-        instance_ami: function.ref aws.ec2.ami.latest.amazon-linux-2
+        instance_ami: aim.ref function.aws.ec2.ami.latest.amazon-linux-2
+
+aim.ref service
+---------------
+
+To refer to a service created in the Services directory, use an ``aim.ref service``. For example:
+
+``aim.ref service.notification.<account>.<region>.applications.notification.groups.lambda.resources.snstopic``
+
+Services are plug-ins that extend AIM with additional functionality. For example, custom notification, patching, back-ups
+and cost optimization services could be developed and installed into an AIM application to provide custom business
+functionality.
 
 aim.sub
 -------
@@ -549,7 +580,7 @@ Networks have the following hierarchy:
                                 - from_port: 80
                                   name: HTTP
                                   protocol: tcp
-                                  source_security_group_id: netenv.ref my-aim-example.network.vpc.security_groups.app.lb.id
+                                  source_security_group_id: aim.ref netenv.my-aim-example.network.vpc.security_groups.app.lb.id
                                   to_port: 80
 
 

docs/quickstart101.rst

@@ -282,7 +282,7 @@ this file will describe your network and looks like this:
                             - from_port: 80
                               name: HTTP
                               protocol: tcp
-                              source_security_group_id: netenv.ref mynet.network.vpc.security_groups.myapp.alb.id
+                              source_security_group_id: aim.ref netenv.mynet.network.vpc.security_groups.myapp.alb.id
                               to_port: 80
             segments:
                 public:
@@ -331,7 +331,7 @@ section. There is only one application in this quickstart and it is named ``myap
                         target_group: myapp
                     scheme: internet-facing
                     security_groups:
-                        - netenv.ref mynet.network.vpc.security_groups.myapp.alb.id
+                        - aim.ref netenv.mynet.network.vpc.security_groups.myapp.alb.id
                     segment: public
                 webserver:
                     type: ASG
@@ -352,9 +352,9 @@ section. There is only one application in this quickstart and it is named ``myap
                     min_instances: 1
                     desired_capacity: 1
                     target_groups:
-                        - netenv.ref mynet.applications.myapp.groups.site.resources.alb.target_groups.myapp.arn
+                        - aim.ref netenv.mynet.applications.myapp.groups.site.resources.alb.target_groups.myapp.arn
                     security_groups:
-                        - netenv.ref mynet.network.vpc.security_groups.myapp.webserver.id
+                        - aim.ref netenv.mynet.network.vpc.security_groups.myapp.webserver.id
                     segment: webserver
                     termination_policies:
                         - Default
@@ -390,7 +390,7 @@ provisioned.
                 myapp:
                     enabled: true
             network:
-                aws_account: config.ref accounts.master
+                aws_account: aim.ref accounts.master
                 vpc:
                     cidr: 10.20.0.0/16
                     segments:
@@ -418,7 +418,7 @@ provisioned.
                                     min_instances: 2
                                     desired_capacity: 2
                 network:
-                    aws_account: config.ref accounts.master
+                    aws_account: aim.ref accounts.master
                     vpc:
                         cidr: 10.20.0.0/16
                         segments:

docs/quickstart102.rst

@@ -41,7 +41,7 @@ at the YAML location ``applications:  myapp: groups``:
         health_check_type: EC2
         instance_iam_role:
           enabled: true
-        instance_ami: function.ref aws.ec2.ami.latest.amazon-linux-2
+        instance_ami: aim.ref function.aws.ec2.ami.latest.amazon-linux-2
         instance_key_pair: aimkeypair
         instance_monitoring: false
         instance_type: t2.micro
@@ -53,7 +53,7 @@ at the YAML location ``applications:  myapp: groups``:
         update_policy_max_batch_size: 1
         update_policy_min_instances_in_service: 0
         security_groups:
-          - netenv.ref mynet.network.vpc.security_groups.myapp.bastion.id
+          - aim.ref netenv.mynet.network.vpc.security_groups.myapp.bastion.id
         user_data_script: |
           #!/bin/bash
           yum update -y
@@ -75,7 +75,7 @@ a new security group:
 .. code-block:: yaml
 
   security_groups:
-    - netenv.ref mynet.network.vpc.security_groups.myapp.bastion.id
+    - aim.ref netenv.mynet.network.vpc.security_groups.myapp.bastion.id
 
 This new ``bastion`` security group will allow SSH access from your IP address to
 EC2 instances that belong to this security group. You will also modify the ``web``
@@ -110,7 +110,7 @@ Then add the following the ingress rule to the ``web:`` security group:
     to_port: 22
     name: SSH
     protocol: tcp
-    source_security_group_id: netenv.ref mynet.network.vpc.security_groups.myapp.bastion.id
+    source_security_group_id: aim.ref netenv.mynet.network.vpc.security_groups.myapp.bastion.id
 
 Your final network configuration should look like this:
 
@@ -161,13 +161,13 @@ Your final network configuration should look like this:
               - from_port: 80
                 name: HTTP
                 protocol: tcp
-                source_security_group_id: netenv.ref mynet.network.vpc.security_groups.myapp.alb.id
+                source_security_group_id: aim.ref netenv.mynet.network.vpc.security_groups.myapp.alb.id
                 to_port: 80
               - from_port: 22
                 to_port: 22
                 name: SSH
                 protocol: tcp
-                source_security_group_id: netenv.ref mynet.network.vpc.security_groups.myapp.bastion.id
+                source_security_group_id: aim.ref netenv.mynet.network.vpc.security_groups.myapp.bastion.id
           bastion:
             egress:
               - cidr_ip: 0.0.0.0/0