Closed ozbillwang closed 8 years ago
Hi @SydOps , the usage for the diff
subcommand is as follows:
<template.rb> diff <stack-name> <options>
Specifically, the argument following diff
is a CloudFormation stack name, not a CloudFormation template file. The diff tool specifically diffs your local Ruby DSL template with a running CloudFormation stack accessible by your account. If you want to diff the JSON results, I recommend a JSON diffing tool, such as Jolt or json-diff.
@jonaf
With EC2InstanceWithSecurityGroupSample.template
, any sample for me to reference on how to provide the stack-name and options?
Could you give some hints?
Do you mean the stack name is the real cloudformation name running in the aws? So the generated *.rb file can used to compare with the real environment?
@SydOps That is, indeed, the intent of this function.
@jonaf It might make sense to extend this to allow feeding in a local template. We do have nice instrumentation on the JSON diff, and it would help unify people's tooling.
@temujin9 Hm, I'm more partial to clarifying the usage in the documentation and perhaps adding a clearer error for this condition. I think other tools can do JSON diffing better than we can, and it doesn't seem to make sense to me to add something like this to the Ruby DSL unless it's really inexpensive to implement/maintain. Thoughts?
We already provide a tool that does JSON diffing. Adding this really just takes rerouting what the second file source is (and a local read is already easier than an HTTP connection). That seems inexpensive, unless I'm missing something.
Let's say you're comparing two versions of your template, and they each take different parameters (maybe your change is to remove a parameter). When you diff them, how do you know which parameters or other options would get applied to each template? I think there may be more edge-cases like this that will complicate things unnecessarily, but this is one possible issue.
He's only asking for comparison against JSON, not between two versions of Ruby template. I agree: two versions would be a coding nightmare. (To accomplish it from outside the tool, expand one template to JSON, then compare against the other.)
@jonaf & @temujin9
Back to my initial question, I make a gist on how to use cloudformation-ruby-dsl
as fresh user.
https://gist.github.com/SydOps/bbfdbb9ca858786ad6c1
But I still didn't know how to use below options properly.
diff
update
cancel-update
delete
describe
describe-resource
get-template
Any documents I can read to get further understanding?
Ideally, we strive for these sub-commands to match roughly what the AWS CLI does for Cloudformation. diff
is a special exception, since it doesn't exist in the AWS CLI. However, all of the other options should work similarly to the corresponding commands in the AWS CLI, in terms of their options and what they actually do.
A brief rundown:
--logical-resource-id <name>
)All commands support these options:
In addition, each command may have further supported options based on what it actually does. For example, the diff
command uses Diffy, so any options aside from the standard four above will be passed straight along to the Diffy default_options
. So you can pass -U
when you use this command, for example, for unified output. See https://github.com/samg/diffy/blob/master/lib/diffy/diff.rb#L3 for a list of options supported by Diffy.
The remainder of the cloudformation-related commands (create
, update
, describe
, etc.) take their cues from the AWS Ruby SDK. So you can pass any option that is configurable to the client, and it will be merged with the other options. See http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Client.html for options related to each of the commands.
There is one exception to the above, and that is describe-resource
, which simply takes an additional argument, which is the logical resource id. So the usage looks something like ./template.rb describe-resource my-stack-name my-logical-resource-id
.
Note that all of this only applies to the latest release of cloudformation-ruby-dsl. Older versions (specifically, pre-1.0) have slightly different behavior because they used different command line tools (the old cfn CLI tools and GNU diff
).
Thanks @jonaf
Your reply is clear enough. I put my understanding here:
diff (no one to one mapping) update (http://docs.aws.amazon.com/cli/latest/reference/cloudformation/update-stack.html) cancel-update (http://docs.aws.amazon.com/cli/latest/reference/cloudformation/cancel-update-stack.html) delete (http://docs.aws.amazon.com/cli/latest/reference/cloudformation/delete-stack.html) describe (http://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stacks.html) describe-resource (http://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stack-resource.html) get-template (http://docs.aws.amazon.com/cli/latest/reference/cloudformation/get-template.html)
The cloudformation template
EC2InstanceWithSecurityGroupSample.template
is downloaded from https://s3-us-west-2.amazonaws.com/cloudformation-templates-us-west-2/EC2InstanceWithSecurityGroupSample.template