Add tags for created objects (#10)

* add createdBy tag to new objects

* fix

* also tag templates

* don't overwrite manually assigned tag

* add template get_tags(), update docs

* update news

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AzureRMR
 Title: Interface to 'Azure Resource Manager'
-Version: 2.3.3
+Version: 2.3.3.9000
 Authors@R: c(
     person("Hong", "Ooi", , "hongooi@microsoft.com", role = c("aut", "cre")),
     person("Microsoft", role="cph")

NEWS.md

@@ -1,3 +1,8 @@
+# AzureRMR 2.3.3.9000
+
+- Add `createdBy:AzureR/AzureRMR` tag to Azure objects (resource groups, resources and templates) created by this package.
+- Add a `get_tags()` method for templates.
+
 # AzureRMR 2.3.3
 
 - Allow for extra resource type-specific fields beyond those mentioned in the Resource Manager documentation. In particular, virtual machines and managed disks may have a `zones` field containing the availability zones.

R/az_resgroup.R

@@ -9,16 +9,16 @@
 #' - `sync_fields()`: Synchronise the R object with the resource group it represents in Azure.
 #' - `list_templates()`: List deployed templates in this resource group.
 #' - `get_template(name)`: Return an object representing an existing template.
-#' - `deploy_template(...)`: Deploy a new template. See 'Templates' for more details.
+#' - `deploy_template(...)`: Deploy a new template. See 'Templates' for more details. By default, AzureRMR will set the `createdBy` tag on a newly-deployed template to the value `AzureR/AzureRMR`.
 #' - `delete_template(name, confirm=TRUE, free_resources=FALSE)`: Delete a deployed template, and optionally free any resources that were created.
 #' - `get_resource(...)`: Return an object representing an existing resource. See 'Resources' for more details.
-#' - `create_resource(...)`: Create a new resource.
+#' - `create_resource(...)`: Create a new resource. By default, AzureRMR will set the `createdBy` tag on a newly-created resource to the value `AzureR/AzureRMR`.
 #' - `delete_resource(..., confirm=TRUE, wait=FALSE)`: Delete an existing resource. Optionally wait for the delete to finish.
 #' - `resource_exists(...)`: Check if a resource exists.
 #' - `list_resources()`: Return a list of resource group objects for this subscription.
 #' - `do_operation(...)`: Carry out an operation. See 'Operations' for more details.
 #' - `set_tags(..., keep_existing=TRUE)`: Set the tags on this resource group. The tags can be either names or name-value pairs. To delete a tag, set it to `NULL`.
-#' - `get_tags()`: Get the tags on this resource.
+#' - `get_tags()`: Get the tags on this resource group.
 #' - `create_lock(name, level)`: Create a management lock on this resource group (which will propagate to all resources within it).
 #' - `get_lock(name)`: Returns a management lock object.
 #' - `delete_lock(name)`: Deletes a management lock object.
@@ -311,6 +311,7 @@ private=list(
     init_and_create=function(name, ...)
     {
         parms <- modifyList(list(...), list(name=name))
+        parms$tags <- add_creator_tag(parms$tags)
         # private$validate_parms(parms)
         self$name <- name
         private$rg_op(body=parms, encode="json", http_verb="PUT")

R/az_resource.R

@@ -347,6 +347,7 @@ private=list(
             properties <- jsonlite::fromJSON(properties[[1]], simplifyVector=FALSE)
 
         # private$validate_deploy_parms(properties)
+        properties$tags <- add_creator_tag(properties$tags)
         private$res_op(body=properties, encode="json", http_verb="PUT")
 
         # do we wait until resource has finished provisioning?

R/az_subscription.R

@@ -9,7 +9,7 @@
 #' - `new(token, id, ...)`: Initialize a subscription object.
 #' - `list_resource_groups()`: Return a list of resource group objects for this subscription.
 #' - `get_resource_group(name)`: Return an object representing an existing resource group.
-#' - `create_resource_group(name, location)`: Create a new resource group in the specified region/location, and return an object representing it.
+#' - `create_resource_group(name, location)`: Create a new resource group in the specified region/location, and return an object representing it. By default, AzureRMR will set the `createdBy` tag on a newly-created resource group to the value `AzureR/AzureRMR`.
 #' - `delete_resource_group(name, confirm=TRUE)`: Delete a resource group, after asking for confirmation.
 #' - `resource_group_exists(name)`: Check if a resource group exists.
 #' - `list_resources()`: List all resources deployed under this subscription.

R/az_template.R

@@ -9,6 +9,7 @@
 #' - `cancel(free_resources=FALSE)`: Cancel an in-progress deployment. Optionally free any resources that have already been created.
 #' - `delete(confirm=TRUE, free_resources=FALSE)`: Delete a deployed template, after a confirmation check. Optionally free any resources that were created. If the template was deployed in Complete mode (its resource group is exclusive to its use), the latter process will delete the entire resource group. Otherwise resources are deleted in the order given by the template's output resources list; in this case, some may be left behind if the ordering is incompatible with dependencies.
 #' - `list_resources()`: Returns a list of Azure resource objects that were created by the template. This returns top-level resources only, not those that represent functionality provided by another resource.
+#' - `get_tags()`: Returns the tags for the deployment template (note: this is not the same as the tags applied to resources that are deployed).
 #'
 #' @section Initialization:
 #' Initializing a new object of this class can either retrieve an existing template, or deploy a new template on the host. Generally, the easiest way to create a template object is via the `get_template`, `deploy_template` or `list_templates` methods of the [az_resource_group] class, which handle the details automatically.
@@ -64,6 +65,7 @@ public=list(
     id=NULL,
     name=NULL,
     properties=NULL,
+    tags=NULL,
     token=NULL,
 
     # constructor overloads: 1) get an existing template from host; 2) from passed-in data; 3) deploy new template
@@ -84,6 +86,7 @@ public=list(
 
         self$id <- parms$id
         self$properties <- parms$properties
+        self$tags <- parms$tags
         NULL
     },
 
@@ -159,6 +162,11 @@ public=list(
         named_list(outlst[!nulls], c("type", "name"))
     },
 
+    get_tags=function()
+    {
+        self$tags
+    },
+
     print=function(...)
     {
         cat("<Azure template ", self$name, ">\n", sep="")
@@ -225,8 +233,9 @@ private=list(
         else append_json(properties, parameters=parameters)
 
         self$name <- name
+        tags <- jsonlite::toJSON(list(createdBy="AzureR/AzureRMR"), auto_unbox=TRUE)
         parms <- private$tpl_op(
-            body=jsonlite::prettify(sprintf('{"properties": %s}', properties)),
+            body=jsonlite::prettify(sprintf('{"properties": %s, "tags": %s}', properties, tags)),
             encode="raw",
             http_verb="PUT"
         )

R/utils.R

@@ -113,3 +113,12 @@ delete_confirmed <- function(confirm, name, type, quote_name=TRUE)
     else utils::askYesNo(msg, FALSE)
     isTRUE(ok)
 }
+
+
+# add a tag on objects created by this package
+add_creator_tag <- function(tags)
+{
+    if(!is.list(tags))
+        tags <- list()
+    utils::modifyList(list(createdBy="AzureR/AzureRMR"), tags)
+}

man/az_resource_group.Rd

@@ -18,16 +18,16 @@ Class representing an Azure resource group.
 \item \code{sync_fields()}: Synchronise the R object with the resource group it represents in Azure.
 \item \code{list_templates()}: List deployed templates in this resource group.
 \item \code{get_template(name)}: Return an object representing an existing template.
-\item \code{deploy_template(...)}: Deploy a new template. See 'Templates' for more details.
+\item \code{deploy_template(...)}: Deploy a new template. See 'Templates' for more details. By default, AzureRMR will set the \code{createdBy} tag on a newly-deployed template to the value \code{AzureR/AzureRMR}.
 \item \code{delete_template(name, confirm=TRUE, free_resources=FALSE)}: Delete a deployed template, and optionally free any resources that were created.
 \item \code{get_resource(...)}: Return an object representing an existing resource. See 'Resources' for more details.
-\item \code{create_resource(...)}: Create a new resource.
+\item \code{create_resource(...)}: Create a new resource. By default, AzureRMR will set the \code{createdBy} tag on a newly-created resource to the value \code{AzureR/AzureRMR}.
 \item \code{delete_resource(..., confirm=TRUE, wait=FALSE)}: Delete an existing resource. Optionally wait for the delete to finish.
 \item \code{resource_exists(...)}: Check if a resource exists.
 \item \code{list_resources()}: Return a list of resource group objects for this subscription.
 \item \code{do_operation(...)}: Carry out an operation. See 'Operations' for more details.
 \item \code{set_tags(..., keep_existing=TRUE)}: Set the tags on this resource group. The tags can be either names or name-value pairs. To delete a tag, set it to \code{NULL}.
-\item \code{get_tags()}: Get the tags on this resource.
+\item \code{get_tags()}: Get the tags on this resource group.
 \item \code{create_lock(name, level)}: Create a management lock on this resource group (which will propagate to all resources within it).
 \item \code{get_lock(name)}: Returns a management lock object.
 \item \code{delete_lock(name)}: Deletes a management lock object.

man/az_subscription.Rd

@@ -16,7 +16,7 @@ Class representing an Azure subscription.
 \item \code{new(token, id, ...)}: Initialize a subscription object.
 \item \code{list_resource_groups()}: Return a list of resource group objects for this subscription.
 \item \code{get_resource_group(name)}: Return an object representing an existing resource group.
-\item \code{create_resource_group(name, location)}: Create a new resource group in the specified region/location, and return an object representing it.
+\item \code{create_resource_group(name, location)}: Create a new resource group in the specified region/location, and return an object representing it. By default, AzureRMR will set the \code{createdBy} tag on a newly-created resource group to the value \code{AzureR/AzureRMR}.
 \item \code{delete_resource_group(name, confirm=TRUE)}: Delete a resource group, after asking for confirmation.
 \item \code{resource_group_exists(name)}: Check if a resource group exists.
 \item \code{list_resources()}: List all resources deployed under this subscription.

man/az_template.Rd

@@ -18,6 +18,7 @@ Class representing an Azure deployment template.
 \item \code{cancel(free_resources=FALSE)}: Cancel an in-progress deployment. Optionally free any resources that have already been created.
 \item \code{delete(confirm=TRUE, free_resources=FALSE)}: Delete a deployed template, after a confirmation check. Optionally free any resources that were created. If the template was deployed in Complete mode (its resource group is exclusive to its use), the latter process will delete the entire resource group. Otherwise resources are deleted in the order given by the template's output resources list; in this case, some may be left behind if the ordering is incompatible with dependencies.
 \item \code{list_resources()}: Returns a list of Azure resource objects that were created by the template. This returns top-level resources only, not those that represent functionality provided by another resource.
+\item \code{get_tags()}: Returns the tags for the deployment template (note: this is not the same as the tags applied to resources that are deployed).
 }
 }
 

tests/testthat/test03_rg.R

@@ -31,11 +31,11 @@ test_that("Resource group methods work",
 
     # tagging
     rgnew$set_tags(tag1="value1")
-    expect_identical(rgnew$get_tags(), list(tag1="value1"))
+    expect_identical(rgnew$get_tags(), list(createdBy="AzureR/AzureRMR", tag1="value1"))
     rgnew$set_tags(tag2)
-    expect_identical(rgnew$get_tags(), list(tag1="value1", tag2=""))
+    expect_identical(rgnew$get_tags(), list(createdBy="AzureR/AzureRMR", tag1="value1", tag2=""))
     rgnew$set_tags(tag2=NULL)
-    expect_identical(rgnew$get_tags(), list(tag1="value1"))
+    expect_identical(rgnew$get_tags(), list(createdBy="AzureR/AzureRMR", tag1="value1"))
     rgnew$set_tags(keep_existing=FALSE)
     expect_true(is_empty(rgnew$get_tags()))
 

tests/testthat/test04_resource.R

@@ -46,11 +46,11 @@ test_that("Resource methods work",
 
     # tagging
     res$set_tags(tag1="value1")
-    expect_identical(res$get_tags(), list(tag1="value1"))
+    expect_identical(res$get_tags(), list(createdBy="AzureR/AzureRMR", tag1="value1"))
     res$set_tags(tag2)
-    expect_identical(res$get_tags(), list(tag1="value1", tag2=""))
+    expect_identical(res$get_tags(), list(createdBy="AzureR/AzureRMR", tag1="value1", tag2=""))
     res$set_tags(tag2=NULL)
-    expect_identical(res$get_tags(), list(tag1="value1"))
+    expect_identical(res$get_tags(), list(createdBy="AzureR/AzureRMR", tag1="value1"))
     res$set_tags(keep_existing=FALSE)
     expect_true(is_empty(res$get_tags()))
 

tests/testthat/test05b_template.R

@@ -72,6 +72,9 @@ test_that("Template methods work",
     tpl4 <- rg$deploy_template(tplname4, template=tpl_def,  parameters=par_def, wait=TRUE)
     tpl4$check()
     expect_is(tpl4, "az_template")
+
+    # tagging
+    expect_identical(tpl4$get_tags(), list(createdBy="AzureR/AzureRMR"))
 })
 
 rg$delete(confirm=FALSE)