Manage CloudFromation Stack tags

Author: Pavel Sinkevych

README.md

@@ -45,6 +45,8 @@ Once running the operator should print some output but shouldn't actually do any
 
 # Demo
 
+## Create stack
+
 Currently you don't have any stacks.
 
 ```console
@@ -104,6 +106,8 @@ status:
 
 Voilà, you just created a CloudFormation stack by only talking to Kubernetes.
 
+## Update stack
+
 You can also update your stack: Let's change the `VersioningConfiguration` from `Suspended` to `Enabled`:
 
 ```yaml
@@ -135,6 +139,39 @@ Wait until the operator discovered and executed the change, then look at your AW
 
 ![Update stack](docs/img/stack-update.png)
 
+## Tags
+
+You may want to assign tags to your CloudFormation stacks. The tags added to a CloudFormation stack will be propagated to the managed resources. This feature may be useful in multiple cases, for example, to distinguish resources at billing report. Current operator provides two ways to assign tags:
+- `global-tags` command line argument or `GLOBAL_TAGS` environment variable which allows setting global tags for all resources managed by the operator. This option accepts JSON format where every key is a tag name and value is a tag value. For example '{"foo": "fooValue", "bar": "barValue"}'
+- `tags` parameter at kubernetes resource spec:
+```yaml
+apiVersion: cloudformation.linki.space/v1alpha1
+kind: Stack
+metadata:
+  name: my-bucket
+spec:
+  tags:
+    foo: dataFromStack
+  template: |
+    ---
+    AWSTemplateFormatVersion: '2010-09-09'
+
+    Resources:
+      S3Bucket:
+        Type: AWS::S3::Bucket
+        Properties:
+          VersioningConfiguration:
+            Status: Enabled
+```
+
+Resource-specific tags have precedence over the global tags. Thus if a tag is defined at command-line arguments and for a `Stack` resource, the value from the `Stack` resource will be used.
+
+If we run the operation and a `Stack` resource with the described above examples, we'll see such picture:
+
+![Stack tags](docs/img/stack-tags.png)
+
+## Parameters
+
 However, often you'll want to extract dynamic values out of your CloudFormation stack template into so called `Parameters` so that your template itself doesn't change that often and, well, is really a *template*.
 
 Let's extract the `VersioningConfiguration` into a parameter:
@@ -175,6 +212,8 @@ Since we changed the template a little this will update your CloudFormation stac
 
 Any CloudFormation parameters defined in the CloudFormation template can be specified in the `Stack` resource's `spec.parameters` section. It's a simple key/value map.
 
+## Outputs
+
 Furthermore, CloudFormation supports so called `Outputs`. These can be used for dynamic values that are only known after a stack has been created.
 In our example, we don't define a particular S3 bucket name but instead let AWS generate one for us.
 
@@ -233,6 +272,8 @@ status:
 
 In the template we defined an `Output` called `BucketName` that should contain the name of our bucket after stack creation. Looking up the corresponding value under `.status.outputs[BucketName]` reveals that our bucket was named `my-bucket-s3bucket-tarusnslfnsj`.
 
+## Delete stack
+
 The operator captures the whole lifecycle of a CloudFormation stack. So if you delete the resource from Kubernetes, the operator will teardown the CloudFormation stack as well. Let's do that now:
 
 ```console
@@ -244,6 +285,16 @@ Check your CloudFormation console once more and validate that your stack as well
 
 ![Delete stack](docs/img/stack-delete.png)
 
+# Command-line arguments
+
+Argument | Environment variable | Default value | Description
+---------|----------------------|---------------|------------
+debug | DEBUG | | Enable debug logging.
+dry-run | DRY_RUN | | If true, don't actually do anything.
+global-tags | GLOBAL_TAGS | {} | Global tags which should be applied for all stacks. Current parameter accepts JSON format where every key-value pair defines a tag. Key is a tag name and value is a tag value.
+namespace | WATCH_NAMESPACE | default | The Kubernetes namespace to watch
+region | AWS_REGION | | The AWS region to use
+
 # Cleanup
 
 Clean up the resources:

cmd/cloudformation-operator/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"runtime"
 
 	"github.com/alecthomas/kingpin"
@@ -17,16 +18,25 @@ import (
 )
 
 var (
-	namespace string
-	region    string
-	dryRun    bool
-	debug     bool
-	version   = "0.2.0+git"
+	namespace  string
+	region     string
+	globalTags string
+	dryRun     bool
+	debug      bool
+	version    = "0.2.0+git"
 )
 
+type Tags map[string]string
+
 func init() {
 	kingpin.Flag("namespace", "The Kubernetes namespace to watch").Default("default").Envar("WATCH_NAMESPACE").StringVar(&namespace)
 	kingpin.Flag("region", "The AWS region to use").Envar("AWS_REGION").StringVar(&region)
+	kingpin.Flag(
+		"global-tags",
+		"Global tags which should be applied for all stacks." +
+		" Current parameter accepts JSON format where every key-value pair defines a tag." +
+		" Key is a tag name and value is a tag value.",
+	).Default("{}").Envar("GLOBAL_TAGS").StringVar(&globalTags)
 	kingpin.Flag("dry-run", "If true, don't actually do anything.").Envar("DRY_RUN").BoolVar(&dryRun)
 	kingpin.Flag("debug", "Enable debug logging.").Envar("DEBUG").BoolVar(&debug)
 }
@@ -38,6 +48,15 @@ func printVersion() {
 	logrus.Infof("cloudformation-operator Version: %v", version)
 }
 
+func parseTags() map[string]string {
+	var globalTagsParsed map[string]string
+	err := json.Unmarshal([]byte(globalTags), &globalTagsParsed)
+	if err != nil {
+		logrus.Error("Failed to parse global tags: ", err)
+	}
+	return globalTagsParsed
+}
+
 func main() {
 	kingpin.Version(version)
 	kingpin.Parse()
@@ -57,6 +76,6 @@ func main() {
 	})
 
 	sdk.Watch("cloudformation.linki.space/v1alpha1", "Stack", namespace, 0)
-	sdk.Handle(stub.NewHandler(client, dryRun))
+	sdk.Handle(stub.NewHandler(client, parseTags(), dryRun))
 	sdk.Run(context.TODO())
 }

docs/img/stack-tags.png

@@ -0,0 +1,17 @@
+apiVersion: cloudformation.linki.space/v1alpha1
+kind: Stack
+metadata:
+  name: my-bucket
+spec:
+  tags:
+    foo: dataFromStack
+  template: |
+    ---
+    AWSTemplateFormatVersion: '2010-09-09'
+
+    Resources:
+      S3Bucket:
+        Type: AWS::S3::Bucket
+        Properties:
+          VersioningConfiguration:
+            Status: Suspended

examples/cfs-my-bucket-tags.yaml

@@ -22,8 +22,9 @@ type Stack struct {
 }
 
 type StackSpec struct {
-	Template   string            `json:"template"`
 	Parameters map[string]string `json:"parameters"`
+	Tags       map[string]string `json:"tags"`
+	Template   string            `json:"template"`
 }
 type StackStatus struct {
 	StackID string            `json:"stackID"`

pkg/apis/cloudformation/v1alpha1/types.go

@@ -29,12 +29,13 @@ var (
 )
 
 type Handler struct {
-	client cloudformationiface.CloudFormationAPI
-	dryRun bool
+	client     cloudformationiface.CloudFormationAPI
+	globalTags map[string]string
+	dryRun     bool
 }
 
-func NewHandler(client cloudformationiface.CloudFormationAPI, dryRun bool) handler.Handler {
-	return &Handler{client: client, dryRun: dryRun}
+func NewHandler(client cloudformationiface.CloudFormationAPI, globalTags map[string]string, dryRun bool) handler.Handler {
+	return &Handler{client: client, globalTags: globalTags, dryRun: dryRun}
 }
 
 func (h *Handler) Handle(ctx types.Context, event types.Event) error {
@@ -81,25 +82,13 @@ func (h *Handler) createStack(stack *v1alpha1.Stack) error {
 		return nil
 	}
 
-	params := []*cloudformation.Parameter{}
-	for k, v := range stack.Spec.Parameters {
-		params = append(params, &cloudformation.Parameter{
-			ParameterKey:   aws.String(k),
-			ParameterValue: aws.String(v),
-		})
-	}
-
 	input := &cloudformation.CreateStackInput{
 		StackName:    aws.String(stack.Name),
 		TemplateBody: aws.String(stack.Spec.Template),
-		Parameters:   params,
-		Tags: []*cloudformation.Tag{
-			{
-				Key:   aws.String(ownerTagKey),
-				Value: aws.String(ownerTagValue),
-			},
-		},
+		Parameters:   h.processStackParams(stack),
+		Tags:         h.processStackTags(stack),
 	}
+
 	if _, err := h.client.CreateStack(input); err != nil {
 		return err
 	}
@@ -119,18 +108,11 @@ func (h *Handler) updateStack(stack *v1alpha1.Stack) error {
 		return nil
 	}
 
-	params := []*cloudformation.Parameter{}
-	for k, v := range stack.Spec.Parameters {
-		params = append(params, &cloudformation.Parameter{
-			ParameterKey:   aws.String(k),
-			ParameterValue: aws.String(v),
-		})
-	}
-
 	input := &cloudformation.UpdateStackInput{
 		StackName:    aws.String(stack.Name),
 		TemplateBody: aws.String(stack.Spec.Template),
-		Parameters:   params,
+		Parameters:   h.processStackParams(stack),
+		Tags:         h.processStackTags(stack),
 	}
 
 	if _, err := h.client.UpdateStack(input); err != nil {
@@ -184,6 +166,39 @@ func (h *Handler) getStack(stack *v1alpha1.Stack) (*cloudformation.Stack, error)
 	return resp.Stacks[0], nil
 }
 
+func (h *Handler) processStackParams(stack *v1alpha1.Stack) ([]*cloudformation.Parameter) {
+	params := []*cloudformation.Parameter{}
+	for k, v := range stack.Spec.Parameters {
+		params = append(params, &cloudformation.Parameter{
+			ParameterKey:   aws.String(k),
+			ParameterValue: aws.String(v),
+		})
+	}
+	return params
+}
+
+func (h *Handler) processStackTags(stack *v1alpha1.Stack) ([]*cloudformation.Tag) {
+	tags := []*cloudformation.Tag{
+		{
+			Key:   aws.String(ownerTagKey),
+			Value: aws.String(ownerTagValue),
+		},
+	}
+	for k, v := range h.globalTags {
+		tags = append(tags, &cloudformation.Tag{
+			Key:   aws.String(k),
+			Value: aws.String(v),
+		})
+	}
+	for k, v := range stack.Spec.Tags {
+		tags = append(tags, &cloudformation.Tag{
+			Key:   aws.String(k),
+			Value: aws.String(v),
+		})
+	}
+	return tags
+}
+
 func (h *Handler) stackExists(stack *v1alpha1.Stack) (bool, error) {
 	_, err := h.getStack(stack)
 	if err != nil {