WO Release/april2026

src/workload-orchestration/HISTORY.rst

@@ -2,6 +2,26 @@
 
 Release History
 ===============
+5.2.0
+++++++
+* **CLI Onboarding Simplification** — reduces onboarding from 11 commands to 4:
+* Added ``az workload-orchestration cluster init`` command:
+  * Prepares Arc-connected clusters for WO (cert-manager, trust-manager, extension, custom location)
+  * Idempotent — safely skips components already installed
+  * Supports ``--release-train``, ``--extension-version``, ``--custom-location-name``
+* Added ``az workload-orchestration hierarchy create`` command:
+  * Creates full hierarchy stack (Site + Configuration + ConfigurationReference) in one command
+  * Supports ResourceGroup (shorthand or YAML) and ServiceGroup (up to 3 levels, recursive)
+  * Handles RBAC propagation waits for ServiceGroup hierarchies
+* Enhanced ``az workload-orchestration context create``:
+  * Added ``--site-id`` argument to auto-create site-reference after context creation
+* Enhanced ``az workload-orchestration target create``:
+  * Added ``--service-group`` argument to auto-link target to a Service Group after creation
+* Enhanced ``az workload-orchestration target install``:
+  * Added ``--solution-template-version-id``, ``--solution-template-name``, ``--solution-template-version`` for full deploy chain (review → publish → install)
+  * Added ``--configuration`` to set config values before review (auto-derives config template args)
+  * Existing ``--solution-version-id`` direct install flow unchanged
+
 5.1.1
 ++++++
 * Resolved solution template name to uniqueIdentifier for ``az workload-orchestration target solution-revision-list`` and ``az workload-orchestration target solution-instance-list``

src/workload-orchestration/azext_workload_orchestration/_help.py

@@ -46,3 +46,62 @@
   - name: Use a specific kubeconfig and context
     text: az workload-orchestration support create-bundle --kube-config ~/.kube/prod-config --kube-context my-cluster
 """
+
+helps['workload-orchestration cluster init'] = """
+type: command
+short-summary: Prepare an Arc-connected Kubernetes cluster for Workload Orchestration.
+long-summary: |
+    Installs all prerequisites on an Arc-connected cluster to make it ready for
+    Workload Orchestration. This is an idempotent operation that skips components
+    already installed.
+
+    Steps performed:
+    1. Verify cluster is Arc-connected with required features enabled
+    2. Install cert-manager (if not present)
+    3. Install trust-manager (if not present)
+    4. Install WO extension (if not present)
+    5. Create custom location (if not present)
+
+    After running this command, use the output custom location ID with
+    'az workload-orchestration target create --extended-location'.
+examples:
+  - name: Initialize a cluster with defaults
+    text: az workload-orchestration cluster init -c my-cluster -g my-rg -l eastus2euap
+  - name: Initialize with a specific release train
+    text: az workload-orchestration cluster init -c my-cluster -g my-rg -l eastus2euap --release-train dev
+  - name: Pin a specific extension version
+    text: az workload-orchestration cluster init -c my-cluster -g my-rg -l eastus2euap --extension-version 2.1.28
+  - name: Custom location name
+    text: az workload-orchestration cluster init -c my-cluster -g my-rg -l eastus2euap --custom-location-name my-cl
+"""
+
+helps['workload-orchestration hierarchy create'] = """
+type: command
+short-summary: Create a hierarchy (Site + Configuration + ConfigurationReference) in one command.
+long-summary: |
+    Creates the full resource stack for a hierarchy level:
+      1. Site (with level label)
+      2. Configuration (in specified region)
+      3. ConfigurationReference (links site to configuration)
+
+    Supports two types:
+      - ResourceGroup (default): single site in a resource group
+      - ServiceGroup: nested sites under a service group (up to 3 levels)
+examples:
+  - name: Create RG hierarchy from YAML file
+    text: az workload-orchestration hierarchy create -g my-rg --configuration-location eastus2euap --hierarchy-spec "@hierarchy.yaml"
+  - name: Create RG hierarchy with shorthand
+    text: az workload-orchestration hierarchy create -g my-rg --configuration-location eastus2euap --hierarchy-spec "name=Mehoopany level=factory"
+  - name: Create ServiceGroup hierarchy from YAML
+    text: az workload-orchestration hierarchy create -g my-rg --configuration-location eastus2euap --hierarchy-spec "@sg-hierarchy.yaml"
+"""
+
+helps['workload-orchestration cluster'] = """
+type: group
+short-summary: Commands for cluster preparation for workload orchestration.
+"""
+
+helps['workload-orchestration hierarchy'] = """
+type: group
+short-summary: Commands for managing workload orchestration hierarchies.
+"""

src/workload-orchestration/azext_workload_orchestration/_params.py

@@ -65,3 +65,82 @@ def load_arguments(self, _):  # pylint: disable=unused-argument
             options_list=['--kube-context'],
             help='Kubernetes context to use. Defaults to current context.',
         )
+        c.argument(
+            'skip_site_reference',
+            options_list=['--skip-site-reference'],
+            action='store_true',
+            help='Skip auto-creation of site-reference to context.',
+        )
+
+    with self.argument_context('workload-orchestration cluster init') as c:
+        c.argument('cluster_name', options_list=['--cluster-name', '-c'],
+                   help='Name of the Arc-connected Kubernetes cluster.', required=True)
+        c.argument('resource_group', options_list=['--resource-group', '-g'],
+                   help='Resource group of the Arc-connected cluster.', required=True)
+        c.argument('location', options_list=['--location', '-l'],
+                   help='Azure region for the custom location (e.g., eastus2euap).', required=True)
+        c.argument('release_train', options_list=['--release-train'],
+                   help='Extension release train. Default: stable.')
+        c.argument('extension_version', options_list=['--extension-version'],
+                   help='Specific WO extension version to install.')
+        c.argument('extension_name', options_list=['--extension-name'],
+                   help='Name for the WO extension resource. Default: wo-extension.')
+        c.argument('custom_location_name', options_list=['--custom-location-name'],
+                   help='Name for the custom location. Default: `<cluster-name>-cl`.')
+
+    with self.argument_context('workload-orchestration hierarchy create') as c:
+        c.argument('resource_group', options_list=['--resource-group', '-g'],
+                   help='Resource group for Configuration resources.', required=True)
+        c.argument('configuration_location', options_list=['--configuration-location', '-l'],
+                   help='Azure region for the Configuration resource (e.g., eastus2euap).', required=True)
+        c.argument('hierarchy_spec', options_list=['--hierarchy-spec'],
+                   help='Hierarchy specification as YAML/JSON file (@file.yaml) or shorthand syntax.',
+                   required=True, type=_parse_hierarchy_spec)
+
+
+def _parse_hierarchy_spec(value):
+    """Parse hierarchy spec from file path, YAML content, or shorthand syntax.
+
+    Handles three input modes:
+    1. File path: 'hierarchy.yaml' or '@hierarchy.yaml' (@ stripped by CLI)
+    2. YAML content: when CLI framework pre-loads @file, we get raw YAML text
+    3. Shorthand: 'name=X level=Y type=Z'
+    """
+    import os
+
+    # Mode 1: File path (with or without @)
+    filepath = value.lstrip('@')
+    if os.path.exists(filepath):
+        try:
+            import yaml
+        except ImportError:
+            import json
+            with open(filepath, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        with open(filepath, 'r', encoding='utf-8') as f:
+            return yaml.safe_load(f)
+
+    # Mode 2: YAML content (CLI framework pre-loaded @file)
+    # Detect YAML by checking for colon-separated key-value or newlines
+    if ':' in value and ('\n' in value or 'name:' in value or 'level:' in value):
+        try:
+            import yaml
+            parsed = yaml.safe_load(value)
+            if isinstance(parsed, dict):
+                return parsed
+        except Exception:
+            pass
+
+    # Mode 3: Shorthand syntax: name=X level=Y type=Z
+    result = {}
+    for pair in value.split():
+        if '=' in pair:
+            k, v = pair.split('=', 1)
+            result[k] = v
+    if not result:
+        from azure.cli.core.azclierror import ValidationError
+        raise ValidationError(
+            f"Invalid hierarchy-spec: '{value}'. "
+            "Use a YAML file path or shorthand: name=X level=Y"
+        )
+    return result

src/workload-orchestration/azext_workload_orchestration/aaz/latest/workload_orchestration/context/_create.py

@@ -9,6 +9,7 @@
 # flake8: noqa
 
 from azure.cli.core.aaz import *
+from azure.cli.core.azclierror import CLIInternalError as CLIError
 
 
 @register_command(
@@ -128,6 +129,14 @@ def _build_arguments_schema(cls, *args, **kwargs):
 
         tags = cls._args_schema.tags
         tags.Element = AAZStrArg()
+
+        # Custom arg: --site-id (not sent to ARM, used in post_operations)
+        _args_schema.site_id = AAZStrArg(
+            options=["--site-id"],
+            arg_group="Onboarding",
+            help="ARM resource ID of a Site to auto-create a site reference after context creation.",
+        )
+
         return cls._args_schema
 
     def _execute_operations(self):
@@ -141,7 +150,47 @@ def pre_operations(self):
 
     @register_callback
     def post_operations(self):
-        pass
+        if hasattr(self.ctx.args, 'site_id') and self.ctx.args.site_id:
+            self._create_site_reference()
+
+    def _create_site_reference(self):
+        """Auto-create a site reference linking the site to this context."""
+        import logging
+        import re
+        logger = logging.getLogger(__name__)
+
+        site_id = str(self.ctx.args.site_id)
+        context_name = str(self.ctx.args.context_name)
+        rg = str(self.ctx.args.resource_group)
+
+        # Extract site name from ARM ID for the reference name
+        site_name = site_id.rstrip("/").split("/")[-1]
+        ref_name = f"{site_name}-ref"
+        # Sanitize: only alphanumeric and hyphens, 3-61 chars
+        ref_name = re.sub(r'[^a-zA-Z0-9-]', '-', ref_name)[:61]
+
+        logger.info("Creating site reference '%s' -> %s", ref_name, site_id)
+
+        try:
+            from azext_workload_orchestration.onboarding.utils import invoke_cli_command, CmdProxy
+            cmd_proxy = CmdProxy(self.ctx.cli_ctx)
+            invoke_cli_command(cmd_proxy, [
+                "workload-orchestration", "context", "site-reference", "create",
+                "-g", rg,
+                "--context-name", context_name,
+                "--site-reference-name", ref_name,
+                "--site-id", site_id,
+            ])
+            logger.info("Site reference '%s' created successfully", ref_name)
+        except Exception as exc:
+            logger.warning("Site reference creation failed: %s", exc)
+            raise CLIError(
+                f"Context created successfully, but site reference creation failed: {exc}\n"
+                f"Run manually:\n"
+                f"  az workload-orchestration context site-reference create "
+                f"-g {rg} --context-name {context_name} "
+                f"--site-reference-name {ref_name} --site-id {site_id}"
+            )
 
     def _output(self, *args, **kwargs):
         result = self.deserialize_output(self.ctx.vars.instance, client_flatten=True)

src/workload-orchestration/azext_workload_orchestration/aaz/latest/workload_orchestration/target/_create.py

@@ -15,6 +15,7 @@
 
 logger = logging.getLogger(__name__)
 
+
 @register_command(
     "workload-orchestration target create",
 )
@@ -117,10 +118,16 @@ def _build_arguments_schema(cls, *args, **kwargs):
             options=["--target-specification"],
             arg_group="Properties",
             help="Specifies that we are using Helm charts for the k8s deployment",
-            required=True,
 
         )
 
+        # Onboarding simplification arguments
+        _args_schema.service_group = AAZStrArg(
+            options=["--service-group"],
+            arg_group="Onboarding",
+            help="ServiceGroup name to auto-link this target to after creation.",
+        )
+
         capabilities = cls._args_schema.capabilities
         capabilities.Element = AAZStrArg()
 
@@ -170,30 +177,64 @@ def _execute_operations(self):
 
     @register_callback
     def pre_operations(self):
-         # If context_id is not provided, try to get it from config
+        # Resolve context_id from CLI config if not provided
         if not self.ctx.args.context_id:
-            try:
-                # Attempt to retrieve the context_id from the config file
-                context_id = self.ctx.cli_ctx.config.get('workload_orchestration', 'context_id')
-                if context_id:
-                    self.ctx.args.context_id = context_id
-                else:
-                    # This else block handles the case where the section exists, but the key is empty
-                    raise CLIInternalError(
-                        "No context-id was provided, and no default context is set. "
-                        "Please provide the --context-id argument or set a default context using 'az workload-orchestration context use'."
-                    )
-            except configparser.NoSectionError as e:
-                logger.debug("Config section 'workload_orchestration' not found: %s", e)
-                # This is the fix: catch the specific error when the [workload_orchestration] section is missing
+            self._resolve_context_id_from_config()
+
+    def _resolve_context_id_from_config(self):
+        """Resolve context_id from CLI config if not already set."""
+        try:
+            context_id = self.ctx.cli_ctx.config.get('workload_orchestration', 'context_id')
+            if context_id:
+                self.ctx.args.context_id = context_id
+            else:
                 raise CLIInternalError(
                     "No context-id was provided, and no default context is set. "
-                    "Please provide the --context-id argument or set a default context using 'az workload-orchestration context use'."
+                    "Please provide the --context-id argument "
+                    "or set a default context using 'az workload-orchestration context use'."
                 )
+        except configparser.NoSectionError as e:
+            logger.debug("Config section 'workload_orchestration' not found: %s", e)
+            raise CLIInternalError(
+                "No context-id was provided, and no default context is set. "
+                "Please provide the --context-id argument "
+                "or set a default context using 'az workload-orchestration context use'."
+            )
 
     @register_callback
     def post_operations(self):
-        pass
+        # --service-group: auto-link target to SG after creation
+        if hasattr(self.ctx.args, 'service_group') and self.ctx.args.service_group:
+            self._handle_service_group_link()
+
+    def _handle_service_group_link(self):
+        """Link the created target to a service group."""
+        from azext_workload_orchestration.onboarding.target_sg_link import (
+            link_target_to_service_group
+        )
+        from azext_workload_orchestration.onboarding.utils import CmdProxy
+        sg_name = str(self.ctx.args.service_group)
+        # Get target ID from the response
+        target_id = None
+        if hasattr(self.ctx.vars, 'instance') and self.ctx.vars.instance:
+            target_id = self.ctx.vars.instance.get("id")
+
+        if not target_id:
+            # Construct it
+            sub_id = self.ctx.subscription_id
+            rg = str(self.ctx.args.resource_group)
+            name = str(self.ctx.args.target_name)
+            target_id = f"/subscriptions/{sub_id}/resourceGroups/{rg}/providers/Microsoft.Edge/targets/{name}"
+
+        import sys
+        print(f"└── service-group Linking to '{sg_name}'...", file=sys.stderr)
+        try:
+            cmd_proxy = CmdProxy(self.ctx.cli_ctx)
+            link_target_to_service_group(cmd_proxy, target_id, sg_name)
+            print(f"└── service-group Linked ✓", file=sys.stderr)
+        except Exception as exc:
+            logger.warning("Service group link failed (non-critical): %s", exc)
+            print(f"└── service-group Link failed (non-critical): {exc}", file=sys.stderr)
 
     def _output(self, *args, **kwargs):
         result = self.deserialize_output(self.ctx.vars.instance, client_flatten=True)