add call_docker_compose

DESCRIPTION

@@ -7,7 +7,7 @@ Authors@R: c(
     person("Ramkumar", "Chandrasekaran", role = "ctb", comment = "Original blog article on Dockerising MMLS"),
     person("Microsoft", role="cph")
     )
-Description: An interface to container functionality in Microsoft's 'Azure' cloud: <https://azure.microsoft.com/en-us/overview/containers/>. Manage 'Azure Container Instance' (ACI), 'Azure Container Registry' (ACR) and 'Azure Kubernetes Service' (AKS) resources, push and pull images, and deploy services. On the client side, lightweight shells to the 'docker', 'kubectl' and 'helm' commandline tools are provided. Part of the 'AzureR' family of packages.
+Description: An interface to container functionality in Microsoft's 'Azure' cloud: <https://azure.microsoft.com/en-us/overview/containers/>. Manage 'Azure Container Instance' (ACI), 'Azure Container Registry' (ACR) and 'Azure Kubernetes Service' (AKS) resources, push and pull images, and deploy services. On the client side, lightweight shells to the 'docker', 'docker-compose', 'kubectl' and 'helm' commandline tools are provided. Part of the 'AzureR' family of packages.
 URL: https://github.com/Azure/AzureContainers https://github.com/Azure/AzureR
 BugReports: https://github.com/Azure/AzureContainers/issues
 License: MIT + file LICENSE

NAMESPACE

@@ -9,6 +9,7 @@ export(acr)
 export(aks)
 export(aks_pools)
 export(call_docker)
+export(call_docker_compose)
 export(call_helm)
 export(call_kubectl)
 export(docker_registry)

NEWS.md

@@ -1,5 +1,6 @@
 # AzureContainers 1.1.2.9000
 
+- New `call_docker_compose` function for calling docker-compose.
 - Add delay in loop to wait for service principal during AKS resource creation; could timeout prematurely otherwise.
 - `KubernetesCluster$create()`, `apply()`, etc now accept HTTP\[S\] URLs as well as filenames as arguments.
 - Use the processx package to run external commands, rather than `base::system2()`. A major benefit of this change is that command output is automatically captured and returned as an R object, making it easier to write automated scripts.

R/AzureContainers.R

@@ -12,6 +12,7 @@ globalVariables("self", "AzureContainers")
 {
     # find docker, kubectl and helm binaries
     .AzureContainers$docker <- Sys.which("docker")
+    .AzureContainers$dockercompose <- Sys.which("docker-compose")
     .AzureContainers$kubectl <- Sys.which("kubectl")
     .AzureContainers$helm <- Sys.which("helm")
 
@@ -27,6 +28,8 @@ globalVariables("self", "AzureContainers")
 {
     if(.AzureContainers$docker != "")
         packageStartupMessage("Using docker binary ", .AzureContainers$docker)
+    if(.AzureContainers$dockercompose != "")
+        packageStartupMessage("Using docker-compose binary ", .AzureContainers$dockercompose)
     if(.AzureContainers$kubectl != "")
         packageStartupMessage("Using kubectl binary ", .AzureContainers$kubectl)
     if(.AzureContainers$helm != "")
@@ -34,6 +37,8 @@ globalVariables("self", "AzureContainers")
 
     if(.AzureContainers$docker == "")
         packageStartupMessage("NOTE: docker binary not found")
+    if(.AzureContainers$dockercompose == "")
+        packageStartupMessage("NOTE: docker-compose binary not found")
     if(.AzureContainers$kubectl == "")
         packageStartupMessage("NOTE: kubectl binary not found")
     if(.AzureContainers$helm == "")

R/docker_registry.R

@@ -355,74 +355,6 @@ docker_registry <- function(server, tenant="common", username=NULL, password=NUL
 }
 
 
-#' Call the docker commandline tool
-#'
-#' @param cmd The docker command line to execute.
-#' @param echo Whether to echo the output of the command to the console.
-#' @param ... Other arguments to pass to [processx::run].
-#'
-#' @details
-#' This function calls the `docker` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
-
-#' @return
-#' A list with the following components:
-#' - `status`: The exit status of the docker tool. If this is `NA`, then the process was killed and had no exit status.
-#' - `stdout`: The standard output of the command, in a character scalar.
-#' - `stderr`: The standard error of the command, in a character scalar.
-#' - `timeout`: Whether the process was killed because of a timeout.
-#' - `cmdline`: The command line.
-#'
-#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
-#'
-#' @seealso
-#' [processx::run], [call_kubectl] for the equivalent interface to the `kubectl` Kubernetes tool
-#'
-#' [docker_registry]
-#'
-#' [Docker command line reference](https://docs.docker.com/engine/reference/commandline/cli/)
-#'
-#' @examples
-#' \dontrun{
-#'
-#' # without any args, prints the docker help screen
-#' call_docker()
-#'
-#' # build an image
-#' call_docker("build -t myimage .")
-#'
-#' # list running containers
-#' call_docker("container ls")
-#'
-#' # prune unused containers and images
-#' call_docker("container prune -f")
-#' call_docker("image prune -f")
-#'
-#' }
-#' @export
-call_docker <- function(cmd="", ..., echo=TRUE)
-{
-    if(.AzureContainers$docker == "")
-        stop("docker binary not found", call.=FALSE)
-    message("Docker operation: ", cmd)
-
-    win <- .Platform$OS.type == "windows"
-    if(!win)
-    {
-        dockercmd <- "sudo"
-        realcmd <- paste(.AzureContainers$docker, cmd)
-    }
-    else
-    {
-        dockercmd <- .AzureContainers$docker
-        realcmd <- cmd
-    }
-
-    val <- processx::run(dockercmd, strsplit(realcmd, " ", fixed=TRUE)[[1]], ..., echo=echo)
-    val$cmdline <- paste("docker", cmd)
-    invisible(val)
-}
-
-
 process_registry_response <- function(response, handler)
 {
     if(handler != "pass")

R/ext_tools.R

@@ -0,0 +1,218 @@
+#' Call the docker commandline tool
+#'
+#' @param cmd The docker command line to execute.
+#' @param echo Whether to echo the output of the command to the console.
+#' @param ... Other arguments to pass to [processx::run].
+#'
+#' @details
+#' This function calls the `docker` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
+
+#' @return
+#' A list with the following components:
+#' - `status`: The exit status of the docker tool. If this is `NA`, then the process was killed and had no exit status.
+#' - `stdout`: The standard output of the command, in a character scalar.
+#' - `stderr`: The standard error of the command, in a character scalar.
+#' - `timeout`: Whether the process was killed because of a timeout.
+#' - `cmdline`: The command line.
+#'
+#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
+#'
+#' @seealso
+#' [processx::run], [call_docker_compose], [call_kubectl] for the equivalent interface to the `kubectl` Kubernetes tool
+#'
+#' [docker_registry]
+#'
+#' [Docker command line reference](https://docs.docker.com/engine/reference/commandline/cli/)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' # without any args, prints the docker help screen
+#' call_docker()
+#'
+#' # build an image
+#' call_docker("build -t myimage .")
+#'
+#' # list running containers
+#' call_docker("container ls")
+#'
+#' # prune unused containers and images
+#' call_docker("container prune -f")
+#' call_docker("image prune -f")
+#'
+#' }
+#' @export
+call_docker <- function(cmd="", ..., echo=TRUE)
+{
+    if(.AzureContainers$docker == "")
+        stop("docker binary not found", call.=FALSE)
+    message("Docker operation: ", cmd)
+
+    win <- .Platform$OS.type == "windows"
+    if(!win)
+    {
+        dockercmd <- "sudo"
+        realcmd <- paste(.AzureContainers$docker, cmd)
+    }
+    else
+    {
+        dockercmd <- .AzureContainers$docker
+        realcmd <- cmd
+    }
+
+    val <- processx::run(dockercmd, strsplit(realcmd, " ", fixed=TRUE)[[1]], ..., echo=echo)
+    val$cmdline <- paste("docker", cmd)
+    invisible(val)
+}
+
+
+#' Call the docker-compose commandline tool
+#'
+#' @param cmd The docker-compose command line to execute.
+#' @param echo Whether to echo the output of the command to the console.
+#' @param ... Other arguments to pass to [processx::run].
+#'
+#' @details
+#' This function calls the `docker-compose` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
+
+#' @return
+#' A list with the following components:
+#' - `status`: The exit status of the docker-compose tool. If this is `NA`, then the process was killed and had no exit status.
+#' - `stdout`: The standard output of the command, in a character scalar.
+#' - `stderr`: The standard error of the command, in a character scalar.
+#' - `timeout`: Whether the process was killed because of a timeout.
+#' - `cmdline`: The command line.
+#'
+#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
+#'
+#' @seealso
+#' [processx::run], [call_docker], [call_kubectl] for the equivalent interface to the `kubectl` Kubernetes tool
+#'
+#' [docker_registry]
+#'
+#' [Docker-compose command line reference](https://docs.docker.com/compose/)
+#' @export
+call_docker_compose <- function(cmd="", ..., echo=TRUE)
+{
+    if(.AzureContainers$docker == "")
+        stop("docker-compose binary not found", call.=FALSE)
+    message("Docker-compose operation: ", cmd)
+
+    win <- .Platform$OS.type == "windows"
+    if(!win)
+    {
+        dcmpcmd <- "sudo"
+        realcmd <- paste(.AzureContainers$dockercompose, cmd)
+    }
+    else
+    {
+        dcmpcmd <- .AzureContainers$dockercompose
+        realcmd <- cmd
+    }
+
+    val <- processx::run(dcmpcmd, strsplit(realcmd, " ", fixed=TRUE)[[1]], ..., echo=echo)
+    val$cmdline <- paste("docker-compose", cmd)
+    invisible(val)
+}
+
+
+#' Call the Kubernetes commandline tool, kubectl
+#'
+#' @param cmd The kubectl command line to execute.
+#' @param echo Whether to echo the output of the command to the console.
+#' @param config The pathname of the cluster config file, if required.
+#' @param ... Other arguments to pass to [processx::run].
+#'
+#' @details
+#' This function calls the `kubectl` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
+
+#' @return
+#' A list with the following components:
+#' - `status`: The exit status of the kubectl tool. If this is `NA`, then the process was killed and had no exit status.
+#' - `stdout`: The standard output of the command, in a character scalar.
+#' - `stderr`: The standard error of the command, in a character scalar.
+#' - `timeout`: Whether the process was killed because of a timeout.
+#' - `cmdline`: The command line.
+#'
+#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
+#'
+#' @seealso
+#' [processx::run], [call_docker], [call_helm]
+#'
+#' [kubernetes_cluster]
+#'
+#' [Kubectl command line reference](https://kubernetes.io/docs/reference/kubectl/overview/)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' # without any args, prints the kubectl help screen
+#' call_kubectl()
+#'
+#' # append "--help" to get help for a command
+#' call_kubectl("create --help")
+#'
+#' # deploy a service from a yaml file
+#' call_kubectl("create -f deployment.yaml")
+#'
+#' # get deployment and service status
+#' call_kubectl("get deployment")
+#' call_kubectl("get service")
+#'
+#' }
+#' @export
+call_kubectl <- function(cmd="", config=NULL, ..., echo=TRUE)
+{
+    if(.AzureContainers$kubectl == "")
+        stop("kubectl binary not found", call.=FALSE)
+
+    if(!is.null(config))
+        config <- paste0("--kubeconfig=", config)
+    message("Kubernetes operation: ", cmd, " ", config)
+    val <- processx::run(.AzureContainers$kubectl, c(strsplit(cmd, " ", fixed=TRUE)[[1]], config), ..., echo=echo)
+    val$cmdline <- paste("kubectl", cmd, config)
+    invisible(val)
+}
+
+
+#' Call the Helm commandline tool
+#'
+#' @param cmd The Helm command line to execute.
+#' @param echo Whether to echo the output of the command to the console.
+#' @param config The pathname of the cluster config file, if required.
+#' @param ... Other arguments to pass to [processx::run].
+#'
+#' @details
+#' This function calls the `helm` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
+
+#' @return
+#' A list with the following components:
+#' - `status`: The exit status of the helm tool. If this is `NA`, then the process was killed and had no exit status.
+#' - `stdout`: The standard output of the command, in a character scalar.
+#' - `stderr`: The standard error of the command, in a character scalar.
+#' - `timeout`: Whether the process was killed because of a timeout.
+#' - `cmdline`: The command line.
+#'
+#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
+#'
+#' @seealso
+#' [processx::run], [call_docker], [call_kubectl]
+#'
+#' [kubernetes_cluster]
+#'
+#' [Kubectl command line reference](https://kubernetes.io/docs/reference/kubectl/overview/)
+#'
+#' @export
+call_helm <- function(cmd="", config=NULL, ..., echo=TRUE)
+{
+    if(.AzureContainers$helm == "")
+        stop("helm binary not found", call.=FALSE)
+
+    if(!is.null(config))
+        config <- paste0("--kubeconfig=", config)
+    message("Helm operation: ", cmd, " ", config)
+    val <- processx::run(.AzureContainers$helm, c(strsplit(cmd, " ", fixed=TRUE)[[1]], config), ..., echo=echo)
+    val$cmdline <- paste("helm", cmd, config)
+    invisible(val)
+}
+

R/kubernetes_cluster.R

@@ -257,107 +257,6 @@ kubernetes_cluster <- function(config=NULL)
 }
 
 
-#' Call the Kubernetes commandline tool, kubectl
-#'
-#' @param cmd The kubectl command line to execute.
-#' @param echo Whether to echo the output of the command to the console.
-#' @param config The pathname of the cluster config file, if required.
-#' @param ... Other arguments to pass to [processx::run].
-#'
-#' @details
-#' This function calls the `kubectl` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
-
-#' @return
-#' A list with the following components:
-#' - `status`: The exit status of the kubectl tool. If this is `NA`, then the process was killed and had no exit status.
-#' - `stdout`: The standard output of the command, in a character scalar.
-#' - `stderr`: The standard error of the command, in a character scalar.
-#' - `timeout`: Whether the process was killed because of a timeout.
-#' - `cmdline`: The command line.
-#'
-#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
-#'
-#' @seealso
-#' [processx::run], [call_docker], [call_helm]
-#'
-#' [kubernetes_cluster]
-#'
-#' [Kubectl command line reference](https://kubernetes.io/docs/reference/kubectl/overview/)
-#'
-#' @examples
-#' \dontrun{
-#'
-#' # without any args, prints the kubectl help screen
-#' call_kubectl()
-#'
-#' # append "--help" to get help for a command
-#' call_kubectl("create --help")
-#'
-#' # deploy a service from a yaml file
-#' call_kubectl("create -f deployment.yaml")
-#'
-#' # get deployment and service status
-#' call_kubectl("get deployment")
-#' call_kubectl("get service")
-#'
-#' }
-#' @export
-call_kubectl <- function(cmd="", config=NULL, ..., echo=TRUE)
-{
-    if(.AzureContainers$kubectl == "")
-        stop("kubectl binary not found", call.=FALSE)
-
-    if(!is.null(config))
-        config <- paste0("--kubeconfig=", config)
-    message("Kubernetes operation: ", cmd, " ", config)
-    val <- processx::run(.AzureContainers$kubectl, c(strsplit(cmd, " ", fixed=TRUE)[[1]], config), ..., echo=echo)
-    val$cmdline <- paste("kubectl", cmd, config)
-    invisible(val)
-}
-
-
-#' Call the Helm commandline tool
-#'
-#' @param cmd The Helm command line to execute.
-#' @param echo Whether to echo the output of the command to the console.
-#' @param config The pathname of the cluster config file, if required.
-#' @param ... Other arguments to pass to [processx::run].
-#'
-#' @details
-#' This function calls the `helm` binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
-
-#' @return
-#' A list with the following components:
-#' - `status`: The exit status of the helm tool. If this is `NA`, then the process was killed and had no exit status.
-#' - `stdout`: The standard output of the command, in a character scalar.
-#' - `stderr`: The standard error of the command, in a character scalar.
-#' - `timeout`: Whether the process was killed because of a timeout.
-#' - `cmdline`: The command line.
-#'
-#' The first four components are from `processx::run`; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
-#'
-#' @seealso
-#' [processx::run], [call_docker], [call_kubectl]
-#'
-#' [kubernetes_cluster]
-#'
-#' [Kubectl command line reference](https://kubernetes.io/docs/reference/kubectl/overview/)
-#'
-#' @export
-call_helm <- function(cmd="", config=NULL, ..., echo=TRUE)
-{
-    if(.AzureContainers$helm == "")
-        stop("helm binary not found", call.=FALSE)
-
-    if(!is.null(config))
-        config <- paste0("--kubeconfig=", config)
-    message("Helm operation: ", cmd, " ", config)
-    val <- processx::run(.AzureContainers$helm, c(strsplit(cmd, " ", fixed=TRUE)[[1]], config), ..., echo=echo)
-    val$cmdline <- paste("helm", cmd, config)
-    invisible(val)
-}
-
-
 # generate a file from a character vector to be passed to kubectl
 make_file <- function(file, ext="")
 {

man/call_docker.Rd

@@ -1,5 +1,5 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/docker_registry.R
+% Please edit documentation in R/ext_tools.R
 \name{call_docker}
 \alias{call_docker}
 \title{Call the docker commandline tool}
@@ -50,7 +50,7 @@ call_docker("image prune -f")
 }
 }
 \seealso{
-\link[processx:run]{processx::run}, \link{call_kubectl} for the equivalent interface to the \code{kubectl} Kubernetes tool
+\link[processx:run]{processx::run}, \link{call_docker_compose}, \link{call_kubectl} for the equivalent interface to the \code{kubectl} Kubernetes tool
 
 \link{docker_registry}
 

man/call_docker_compose.Rd

@@ -0,0 +1,40 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/ext_tools.R
+\name{call_docker_compose}
+\alias{call_docker_compose}
+\title{Call the docker-compose commandline tool}
+\usage{
+call_docker_compose(cmd = "", ..., echo = TRUE)
+}
+\arguments{
+\item{cmd}{The docker-compose command line to execute.}
+
+\item{...}{Other arguments to pass to \link[processx:run]{processx::run}.}
+
+\item{echo}{Whether to echo the output of the command to the console.}
+}
+\value{
+A list with the following components:
+\itemize{
+\item \code{status}: The exit status of the docker-compose tool. If this is \code{NA}, then the process was killed and had no exit status.
+\item \code{stdout}: The standard output of the command, in a character scalar.
+\item \code{stderr}: The standard error of the command, in a character scalar.
+\item \code{timeout}: Whether the process was killed because of a timeout.
+\item \code{cmdline}: The command line.
+}
+
+The first four components are from \code{processx::run}; AzureContainers adds the last to make it easier to construct scripts that can be run outside R.
+}
+\description{
+Call the docker-compose commandline tool
+}
+\details{
+This function calls the \code{docker-compose} binary, which must be located in your search path. AzureContainers will search for the binary at package startup, and print a warning if it is not found.
+}
+\seealso{
+\link[processx:run]{processx::run}, \link{call_docker}, \link{call_kubectl} for the equivalent interface to the \code{kubectl} Kubernetes tool
+
+\link{docker_registry}
+
+\href{https://docs.docker.com/compose/}{Docker-compose command line reference}
+}

man/call_helm.Rd

@@ -1,5 +1,5 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/kubernetes_cluster.R
+% Please edit documentation in R/ext_tools.R
 \name{call_helm}
 \alias{call_helm}
 \title{Call the Helm commandline tool}

man/call_kubectl.Rd

@@ -1,5 +1,5 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/kubernetes_cluster.R
+% Please edit documentation in R/ext_tools.R
 \name{call_kubectl}
 \alias{call_kubectl}
 \title{Call the Kubernetes commandline tool, kubectl}