Skip to content

Commit

Permalink
Add asoctl template command (#3968)
Browse files Browse the repository at this point in the history
* Add asoctl template command

Fixes #3719.

* Docs updates
  • Loading branch information
matthchr authored Apr 24, 2024
1 parent 8496cd4 commit 8ed1f77
Show file tree
Hide file tree
Showing 9 changed files with 433 additions and 11 deletions.
7 changes: 6 additions & 1 deletion .github/workflows/create-release-experimental.yml
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,13 @@ jobs:
> ⚠️ The provided YAML manifest does not configure any CRDs to install by default, but is required.
> You must specify the CRDs that you want to use as part of `crdPattern`, for example `'resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;apimanagement.azure.com/*'`.
The recommended way to supply `crdPattern` is using [asoctl template](https://azure.github.io/azure-service-operator/tools/asoctl/#template):
```bash
asoctl template https://github.com/Azure/azure-service-operator/releases/download/experimental/azureserviceoperator_experimental.yaml --crd-pattern "<pattern>" | kubectl apply -f -`
```
It is only intended for developers wishing to try out the latest feature, some of which may not be fully implemented.
This release is only intended for developers wishing to try out the latest features, some of which may not be fully implemented.
It is not recommended to run the experimental release for a long period of time, as the docker image referenced by the deployment is
`mcr.microsoft.com/k8s/azureserviceoperator:experimental`, which is always being updated. Test what you want to test and then uninstall the operator.
Expand Down
37 changes: 31 additions & 6 deletions docs/hugo/content/guide/installing-from-yaml.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,19 @@ weight: -4
2. You have the `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET` environment variables set from the
[installation instructions](../../#installation).

## Installation
## Installation (operator)

1. Install [the latest **v2+** release](https://github.com/Azure/azure-service-operator/releases) of Azure Service Operator.
1. Download and install the latest version of [asoctl]({{<relref "asoctl#installation">}}).
2. Install [the latest **v2+** release](https://github.com/Azure/azure-service-operator/releases) of Azure Service Operator.
```bash
kubectl apply --server-side=true -f https://github.com/Azure/azure-service-operator/releases/download/v2.0.0/azureserviceoperator_v2.0.0.yaml
asoctl export template --version v2.6.0 --crd-pattern "<your pattern>" | kubectl apply -f -
```
2. Create the Azure Service Operator v2 secret. This secret contains the identity that Azure Service Operator will run as.

When specifying `--crd-pattern`, ensure you choose only the CRDs you need, for example:
`--crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*"`.
For more information about what `--crd-pattern` means, see [CRD management in ASO]({{<relref "crd-management">}}).

3. Create the Azure Service Operator v2 secret. This secret contains the identity that Azure Service Operator will run as.
Make sure that you have the 4 environment variables from the [Helm installation instructions](../../#installation) set.
To learn more about other authentication options, see the [authentication documentation](../authentication/):
```bash
Expand All @@ -31,9 +37,28 @@ weight: -4
EOF
```
## Troubleshooting
## Installation (crds)
The operator manages its own CRDs by default, based on the `--crd-pattern` specified during installation.
{{% alert title="Warning" color="warning" %}}
If you specified `--crd-pattern` when installing ASO, you don't need to do any of the below.
{{% /alert %}}
If you don't want the operator to manage the CRDs itself, you can install the latest version of the CRDs yourself:
```bash
kubectl apply --server-side=true -f https://github.com/Azure/azure-service-operator/releases/download/v2.6.0/azureserviceoperator_customresourcedefinitions_v2.6.0.yaml
```
{{% alert title="Warning" color="warning" %}}
The azureserviceoperator_customresourcedefinitions_v2.6.0.yaml file contains _all_ the supported CRDs. We recommend filtering
it locally to only the CRDs you want.
{{% /alert %}}
### Troubleshooting
### Metadata too long
#### Metadata too long
If you omit the `--server-side=true` flag from the `kubectl apply` command, you will see an error like the following:
Expand Down
52 changes: 50 additions & 2 deletions docs/hugo/content/tools/asoctl.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,19 @@ Usage:
asoctl [command]

Available Commands:
clean Clean Custom Resource Definitions (CRDs) prior to upgrade
completion Generate the autocompletion script for the specified shell
crd Custom Resource Definition (CRD) related actions
export Exports an ASO YAML file from a template
help Help about any command
import imports ARM resources as YAML resource definitions
import Imports ARM resources to YAML files containing ASO custom resource definitions
version Display version information

Flags:
--quiet Silence most logging
--verbose Enable verbose logging
-h, --help help for asoctl

Use "asoctl [command] --help" for more information about a command.
```

## Installation
Expand Down Expand Up @@ -94,6 +102,46 @@ Append that directory to your `PATH` if desired.
{{% /tab %}}
{{< /tabpane >}}

## Export template

The `export template` commands helps render a YAML file from the raw ASO published with each release.

```bash
Template creates a YAML file from the specified ASO yaml template
Usage:
asoctl export template [--source <string> |--version <string>] [--crd-pattern <string>|--raw] [flags]
Examples:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"
With combined crd-pattern:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*"
With remote source:
asoctl export template --source https://github.com/Azure/azure-service-operator/releases/download/v2.6.0/azureserviceoperator_v2.6.0.yaml --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"
With local source:
asoctl export template --source ~/Downloads/azureserviceoperator_v2.6.0.yaml --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"
Raw:
asoctl export template --version v2.6.0 --raw
With kubectl:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*" | kubectl apply -f -
Flags:
-p, --crd-pattern strings What new CRDs to install. Existing ASO CRDs in the cluster will always be upgraded even if crdPattern is empty. See https://azure.github.io/azure-service-operator/guide/crd-management/ for more details.
-h, --help help for template
--raw Export the YAML without any variable replacements
-s, --source string File or URL path to the ASO YAML template. Use this if you've customized the base ASO YAML locally or are using a base YAML other than the one hosted at https://github.com/Azure/azure-service-operator/tags
-v, --version string Release version to use.
Global Flags:
--quiet Silence most logging
--verbose Enable verbose logging
```
## Clean CRDs
This command can be used to prepare ASOv2 `v1alpha1api`(deprecated in v2.0.0) CustomResources and CustomResourceDefinitions for ASO `v2.0.0` release.
Expand Down
21 changes: 21 additions & 0 deletions v2/cmd/asoctl/cmd/export.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
/*
* Copyright (c) Microsoft Corporation.
* Licensed under the MIT license.
*/

package cmd

import "github.com/spf13/cobra"

// newExportCommand creates a new cobra Command when invoked from the command line
func newExportCommand() (*cobra.Command, error) {
cmd := &cobra.Command{
Use: "export",
Short: "Exports an ASO YAML file from a template",
Args: cobra.NoArgs,
}

cmd.AddCommand(newTemplateCommand())

return cmd, nil
}
6 changes: 4 additions & 2 deletions v2/cmd/asoctl/cmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,12 @@ package cmd
import (
"context"

"github.com/Azure/azure-service-operator/v2/internal/version"
"github.com/Azure/azure-service-operator/v2/pkg/xcontext"
"github.com/go-logr/zerologr"
"github.com/rs/zerolog"
"github.com/spf13/cobra"

"github.com/Azure/azure-service-operator/v2/internal/version"
"github.com/Azure/azure-service-operator/v2/pkg/xcontext"
)

// Execute kicks off the command line
Expand Down Expand Up @@ -48,6 +49,7 @@ func newRootCommand() (*cobra.Command, error) {
cmds := []func() (*cobra.Command, error){
newCleanCommand,
newImportCommand,
newExportCommand,
version.NewCommand,
}

Expand Down
124 changes: 124 additions & 0 deletions v2/cmd/asoctl/cmd/template.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
/*
* Copyright (c) Microsoft Corporation.
* Licensed under the MIT license.
*/

package cmd

import (
"os"
"regexp"
"strings"

"github.com/pkg/errors"
"github.com/spf13/cobra"

"github.com/Azure/azure-service-operator/v2/cmd/asoctl/internal/template"
)

type templateOptions struct {
source string
version string

raw bool
crdPattern []string
}

var expectedVersionRegex = regexp.MustCompile(`^v\d\.\d\.\d$`)

// newTemplateCommand creates a new cobra Command when invoked from the command line
func newTemplateCommand() *cobra.Command {
var options templateOptions

cmd := &cobra.Command{
Use: "template [--source <string> |--version <string>] [--crd-pattern <string>|--raw]",
Short: "Template creates a YAML file from the specified ASO yaml template",
Example: `asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"
With combined crd-pattern:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*"
With remote source:
asoctl export template --source https://github.com/Azure/azure-service-operator/releases/download/v2.6.0/azureserviceoperator_v2.6.0.yaml --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"
With local source:
asoctl export template --source ~/Downloads/azureserviceoperator_v2.6.0.yaml --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"
Raw:
asoctl export template --version v2.6.0 --raw
With kubectl:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*" | kubectl apply -f -`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, args []string) error {
ctx := cmd.Context()
var uri string

if options.source != "" {
uri = options.source
} else {
if !expectedVersionRegex.MatchString(options.version) {
return errors.New("specified version doesn't match expected format 'v#.#.#' (example: v2.6.0)")
}

uri = template.URIFromVersion(options.version)
}

result, err := template.Get(ctx, uri)
if err != nil {
return err
}

if !options.raw {
// Render the CRDPattern w/ `;` separating them
crdPattern := strings.Join(options.crdPattern, ";")
result, err = template.Apply(result, crdPattern)
if err != nil {
return err
}
}

_, err = os.Stdout.WriteString(result)
if err != nil {
return err
}

return nil
},
}

cmd.Flags().StringVarP(
&options.source,
"source",
"s",
"",
"File or URL path to the ASO YAML template. Use this if you've customized the base ASO YAML locally or are using a base YAML other than the one hosted at https://github.com/Azure/azure-service-operator/tags")

cmd.Flags().StringVarP(
&options.version,
"version",
"v",
"",
"Release version to use.")

cmd.MarkFlagsOneRequired("source", "version")
cmd.MarkFlagsMutuallyExclusive("source", "version")

cmd.Flags().BoolVar(
&options.raw,
"raw",
false,
"Export the YAML without any variable replacements")

cmd.Flags().StringSliceVarP(
&options.crdPattern,
"crd-pattern",
"p",
nil,
"What new CRDs to install. Existing ASO CRDs in the cluster will always be upgraded even if crdPattern is empty. See https://azure.github.io/azure-service-operator/guide/crd-management/ for more details.")

cmd.MarkFlagsOneRequired("crd-pattern", "raw")
cmd.MarkFlagsMutuallyExclusive("crd-pattern", "raw")

return cmd
}
Loading

0 comments on commit 8ed1f77

Please sign in to comment.