From 78f0421e76cbb5a0f996d01a9d95794bd1c7c929 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 19 Jun 2026 09:34:58 +0200 Subject: [PATCH 1/5] z/OS Connect deployment support in zDeploy Signed-off-by: Dennis Behm --- WaziDeploy/zDeploy/README.md | 22 +-- .../deployment-configuration/README.md | 61 +++++--- .../deployment-configuration/VALIDATION.md | 145 ++++++++++++++++++ .../deployment-method.yml | 84 ++++++++-- .../global/global_initialization.yml | 1 + .../global/types_pattern_mapping.yml | 8 + .../global/zos_connect.yaml | 25 +++ .../templates/zos_connect_app_config.xml.j2 | 3 + .../python/EOLEB7-Acceptance.yml | 5 + .../python/EOLEB7-Integration.yml | 5 + .../python/EOLEB7-Production.yml | 5 + .../python/README.md | 69 +++++---- 12 files changed, 361 insertions(+), 72 deletions(-) create mode 100644 WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md create mode 100644 WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml create mode 100644 WaziDeploy/zDeploy/deployment-configuration/templates/zos_connect_app_config.xml.j2 diff --git a/WaziDeploy/zDeploy/README.md b/WaziDeploy/zDeploy/README.md index ba53deff..935e34a7 100644 --- a/WaziDeploy/zDeploy/README.md +++ b/WaziDeploy/zDeploy/README.md @@ -36,16 +36,18 @@ The core configuration sets parameters for the Wazi Deploy specific building blo │ • pds_spec.yml │ │ │ │ • cics_config.yml │ ┌─────────▼─────────┐ ┌──────────▼────────┐ │ • db2_config.yml │ │ default_* vars │ │ app_* vars │ - │ • jcl_verify.yml │ │ /python/ or │ │ /application- │ - │ • shell_cmds.yml │ │ /ansible/ │ │ overrides/ │ - │ │ │ │ │ │ - │ Templates: │ │ Environment │ │ Application │ - │ • cics_csd.jcl.j2 │ │ Defaults: │ │ Overrides: │ - │ • jcl_expert.jcl.j2│ │ • HLQ │ │ • app_db2_* │ - └─────────────────────┘ │ • USS paths │ │ • app_cics_* │ - │ • CICS subsys │ │ • app_jcl_* │ - │ • DB2 subsys │ │ • app_jobcard │ - │ • Job cards │ │ │ + │ • zos_connect.yaml │ │ /python/ or │ │ /application- │ + │ • jcl_verify.yml │ │ /ansible/ │ │ overrides/ │ + │ • shell_cmds.yml │ │ │ │ │ + │ │ │ Environment │ │ Application │ + │ Templates: │ │ Defaults: │ │ Overrides: │ + │ • cics_csd.jcl.j2 │ │ • HLQ │ │ • app_db2_* │ + │ • jcl_expert.jcl.j2│ │ • USS paths │ │ • app_cics_* │ + │ • zos_connect_app_ │ │ • CICS subsys │ │ • app_jcl_* │ + │ config.xml.j2 │ │ • DB2 subsys │ │ • app_jobcard │ + │ │ │ • Job cards │ │ • app_zos_ │ + └─────────────────────┘ │ • z/OS Connect │ │ connect_* │ + │ server │ │ │ └───────────────────┘ └───────────────────┘ ``` diff --git a/WaziDeploy/zDeploy/deployment-configuration/README.md b/WaziDeploy/zDeploy/deployment-configuration/README.md index e760cdb8..07ceb588 100644 --- a/WaziDeploy/zDeploy/deployment-configuration/README.md +++ b/WaziDeploy/zDeploy/deployment-configuration/README.md @@ -40,22 +40,25 @@ Plan tags control which activities are executed during deployment: | Activity Name | Description | |----------------------|---------------------------------------------------------------------------------------------------| -| CONFIG | Loads all deployment configuration variables, including application, middleware, and common/global | +| LOAD_CONFIG | Loads all deployment configuration variables, including global, application, middleware, and common settings | | PACKAGE | Expands the deployment package into the working directory | -| DB2 | Handles DBRM modules: deletion, update (copy to temp), and DB2 bind operations | +| CICS_REGION | Applies CICS Resource Builder configurations (CSD updates) to the target CICS region | +| DBRMS | Handles DBRM modules: deletion, update (copy to temp), and DB2 bind operations (package and plan) | | DEPLOY_MODULES | Deploys application artifacts (LOAD, DBRM, CICSLOAD, MAPLOAD, JCL) into target PDS libraries | -| ROLLBACK_MODULES | Restores artifacts from backup PDS libraries and supports DB2 bind rollback for the rollback scenario | -| VERIFICATION | Verifies deployed JCLs using the JCL Expert tool | -| CICS | Activates CICS artifacts online via CMCI | +| ROLLBACK_MODULES | Restores artifacts from backup PDS libraries and supports DB2 bind rollback for the rollback scenario | +| VERIFICATION | Verifies deployed JCLs using the JCL Expert tool (optional, conditional on environment setting) | +| CICS_ACTIVATION | Activates CICS artifacts (CICSLOAD, MAPLOAD) online via CMCI program updates | +| DEPLOY_ZOS_CONNECT | Deploys z/OS Connect artifacts (war files) and configuration files to USS | #### Detailed Activity Descriptions -**CONFIG** +**LOAD_CONFIG** -Loads all required configuration variables for the deployment. This includes: -- Application-specific variables (environment dependent) from [../environment-configuration/](../environment-configuration/) -- Middleware variables (e.g., DB2, CICS) from [global](global/) -- Common/global variables (e.g., type mappings, dataset specs) from [global](global/) +Loads all required configuration variables for the deployment in the following order: +1. Global initialization settings from [global/global_initialization.yml](global/global_initialization.yml) +2. Application-specific variables (environment dependent) from [../environment-configuration/](../environment-configuration/) +3. Middleware variables (e.g., DB2, CICS) from [global](global/) +4. Common/global variables (e.g., type mappings, dataset specs) from [global](global/) This step ensures all subsequent activities have the necessary context and settings. @@ -63,12 +66,17 @@ This step ensures all subsequent activities have the necessary context and setti Expands the deployment package into the working directory, preparing the artifacts for further processing and deployment. -**DB2** +**CICS_REGION** + +Applies CICS Resource Builder configurations to the target CICS region. This activity processes CSD (CICS System Definition) artifacts by submitting batch JCL to update CICS resource definitions. + +**DBRMS** This activity is dedicated to handling DBRM modules. It is always processed first, before deploying application executables. The steps include: - Deleting obsolete DBRMs (with backup) - Updating DBRMs by copying them into a temporary PDS library (configured via `type_dbrm_temp` in [types_pattern_mapping.yml](global/types_pattern_mapping.yml)) -- Performing DB2 bind operations (package and plan) using the temporary dataset +- Performing DB2 bind package operations using the temporary dataset +- Performing DB2 bind plan operations using the temporary dataset The temporary dataset approach (`{{ hlq }}.TMP.DBRM`) ensures that: - DB2 bind operations can access DBRMs without conflicts @@ -83,19 +91,28 @@ Deploys application artifacts (LOAD, DBRM, CICSLOAD, MAPLOAD, JCL) into their re **ROLLBACK_MODULES** -Restores artifacts from backup PDS libraries in case a rollback is required. Also supports DB2 bind rollback operations for DBRM modules. This is dedicated to the rollback scenarios. +Restores artifacts from backup PDS libraries in case a rollback is required. This activity includes: +- Restoring members from backup datasets for all artifact types +- Performing DB2 bind package and plan operations for restored DBRM modules + +This is dedicated to the rollback scenarios and only executes when the `restore` plan tag is provided. **VERIFICATION** -Verifies the correctness of deployed JCLs using the JCL Expert tool. This step scans and validates JCL members, ensuring compliance and quality before activation. +Verifies the correctness of deployed JCLs using the JCL Expert tool. This step scans and validates JCL members, ensuring compliance and quality before activation. This activity is optional and only runs when `environment.run_jcl_expert` is set to true. It uses a loop to process each JCL member individually. + +**CICS_ACTIVATION** + +Handles the online activation of CICS artifacts (CICSLOAD, MAPLOAD) using the CMCI interface. This activity refreshes CICS programs and maps via CMCI program update operations (NEWCOPY). This step ensures that updated modules are activated in the CICS region and is also used during restore operations. -**CICS** +**DEPLOY_ZOS_CONNECT** -Handles the online activation of CICS artifacts (CICSLOAD, MAPLOAD) using the CMCI interface. This activity includes: -- CSD (CICS System Definition) updates via batch JCL submission -- Program updates (NEWCOPY) via CMCI for CICSLOAD and MAPLOAD modules +Handles IBM z/OS Connect artifacts deployment. This activity includes: +- Restoring war files to Unix System Services (USS) with backup and restore capabilities +- Processing and deploying z/OS Connect configuration files with variable substitution using templates +- Refreshing z/OS Connect server configuration and applications via system modify commands -This step ensures that updated modules are activated in the CICS region. +This activity supports both initial deployment and rollback scenarios for z/OS Connect applications. ## Templates @@ -105,15 +122,19 @@ The [templates/](templates/) directory contains Jinja2 templates used for genera |-----------------------------------|----------------------------------------------------------------| | `cics_csd_dfhcsdup.jcl.j2` | CICS CSD update JCL template using DFHCSDUP utility | | `jcl_expert_validation.jcl.j2` | JCL Expert validation template for verifying deployed JCLs | +| `zos_connect_app_config.xml.j2` | z/OS Connect application configuration template with variable substitution | These templates are referenced in the configuration files and populated with environment-specific variables during deployment. ## Configuration Files See the [global/](global/) directory for detailed information about: +- Global initialization settings - CICS configuration settings - DB2 configuration settings +- z/OS Connect configuration settings - Type pattern mappings - PDS specifications - JCL verification rules -- Shell command templates \ No newline at end of file +- Shell command templates +- Other default settings \ No newline at end of file diff --git a/WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md b/WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md new file mode 100644 index 00000000..f2af1491 --- /dev/null +++ b/WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md @@ -0,0 +1,145 @@ +# YAML Schema Validation + +This directory contains tools for validating the `deployment-method.yml` file against its JSON schema. + +## Prerequisites + +### Python Virtual Environment + +The VS Code tasks are configured to use the Python virtual environment at: +``` +/Users/dennisbehm/devops-venv/bin/activate +``` + +Install the required Python packages in the virtual environment: + +```bash +source /Users/dennisbehm/devops-venv/bin/activate +pip install pyyaml jsonschema +``` + +Or use the VS Code task: **"Install Python Dependencies for YAML Validation"** (automatically activates the venv) + +## Validation Methods + +### 1. VS Code Tasks (Recommended) + +Three VS Code tasks are available in the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`): + +#### Task: "Validate Deployment Method YAML Schema" +- **Usage**: Open any YAML file and run this task +- **Description**: Validates the currently open file against the schema +- **Best for**: Validating any YAML file in the workspace + +#### Task: "Validate Deployment Method YAML (Fixed Path)" +- **Usage**: Run from anywhere in the workspace +- **Description**: Always validates `deployment-method.yml` specifically +- **Best for**: Quick validation of the main deployment method file + +#### Task: "Install Python Dependencies for YAML Validation" +- **Usage**: Run once to install dependencies +- **Description**: Installs `pyyaml` and `jsonschema` packages + +### 2. Command Line + +Run the validation script directly with the virtual environment: + +```bash +# Activate the virtual environment first +source /Users/dennisbehm/devops-venv/bin/activate + +# From the deployment-configuration directory +python3 validate_schema.py \ + deployment-method.yml \ + ../../Schemas/dep-method-schema.json + +# From the workspace root +python3 WaziDeploy/zDeploy/deployment-configuration/validate_schema.py \ + WaziDeploy/zDeploy/deployment-configuration/deployment-method.yml \ + WaziDeploy/Schemas/dep-method-schema.json +``` + +### 3. GitHub Actions / CI Pipeline + +For automated validation in CI/CD pipelines, see the examples in the main repository documentation. + +## Output Examples + +### Successful Validation +``` +====================================================================== +YAML Schema Validation +====================================================================== +✓ Loaded YAML file: deployment-method.yml +✓ Loaded schema file: ../../Schemas/dep-method-schema.json + +✅ YAML validation successful! + File: deployment-method.yml + Schema: ../../Schemas/dep-method-schema.json +====================================================================== +``` + +### Failed Validation +``` +====================================================================== +YAML Schema Validation +====================================================================== +✓ Loaded YAML file: deployment-method.yml +✓ Loaded schema file: ../../Schemas/dep-method-schema.json + +❌ Validation failed with 2 error(s): + +Error 1: + Location: metadata + Message: 'name' is a required property + Validator: required + +Error 2: + Location: activities → 0 → actions + Message: [] is too short + Validator: minItems + +====================================================================== +``` + +## Schema Reference + +The validation uses the JSON Schema Draft 7 specification: +- **Schema Location**: `WaziDeploy/Schemas/dep-method-schema.json` +- **Schema URL**: https://github.com/IBM/dbb/raw/refs/heads/main/Wazi_Deploy/Schemas/dep-method-schema.json + +## Troubleshooting + +### Python Not Found +If you get a "python3: command not found" error: +- Install Python 3.7 or later +- On macOS: `brew install python3` +- On Linux: `sudo apt-get install python3` + +### Missing Dependencies +If you get import errors, install packages in the virtual environment: +```bash +source /Users/dennisbehm/devops-venv/bin/activate +pip install pyyaml jsonschema +``` + +### Permission Denied +Make the script executable: +```bash +chmod +x validate_schema.py +``` + +## Integration with VS Code + +The validation script is integrated with VS Code through tasks defined in `.vscode/tasks.json`. You can: + +1. Run tasks via Command Palette: `Tasks: Run Task` +2. Bind tasks to keyboard shortcuts in `keybindings.json` +3. Add tasks to the status bar with extensions like "Task Runner" + +## Additional Resources + +- [JSON Schema Documentation](https://json-schema.org/) +- [Wazi Deploy Documentation](https://www.ibm.com/docs/en/wazi-deploy) +- [PyYAML Documentation](https://pyyaml.org/) +- [jsonschema Python Package](https://python-jsonschema.readthedocs.io/) \ No newline at end of file diff --git a/WaziDeploy/zDeploy/deployment-configuration/deployment-method.yml b/WaziDeploy/zDeploy/deployment-configuration/deployment-method.yml index 6742aef6..bb0db6b3 100755 --- a/WaziDeploy/zDeploy/deployment-configuration/deployment-method.yml +++ b/WaziDeploy/zDeploy/deployment-configuration/deployment-method.yml @@ -91,21 +91,21 @@ activities: states: - UNDEFINED steps: - - name: UPDATE - is_artifact: true - properties: - - key: template - value: job_submit - - key: var_job_submit - value: csd_update_template + - name: UPDATE + is_artifact: true + properties: + - key: template + value: job_submit + - key: var_job_submit + value: csd_update_template # activity to process DBRMs always first - # * A tag is used to be able to run these actions only and skip others + # * A tag is used to be able to run these actions only and skip others # in it's own run # * member_copy is configured to move the DBRM into a temp library first - name: DBRMS description: | - This activity is dedicated to DBRM bind modules and will process DBRM members of the package first using dedicated PDS libraries + This activity is dedicated to DBRM bind modules and will process DBRM members of the package first using dedicated PDS libraries short_name: DBRMS actions: # Manage deletions of DBRMS @@ -210,7 +210,7 @@ activities: short_name: ROLLBACK_MODULES description: | This action is applicable when when restoring files from the backup - datasets. It is only executed when plan_tags 'restore' is provided. + datasets. It is only executed when plan_tags 'restore' is provided. actions: - name: RESTORE description: | @@ -223,7 +223,7 @@ activities: # Invoke Bind operations - name: BIND types: - - name: "DBRM" + - name: "DBRM" description: | This action runs Db2 Bind package and plan for restored DBRM members steps: @@ -233,14 +233,14 @@ activities: This step performs the DB2 Bind package operations for restored DBRM members properties: - key: template - value: db2_bind_package + value: db2_bind_package - name: BIND_PLAN short_name: BIND_PLAN description: | This step performs the DB2 Bind plan operations for restored DBRM members properties: - key: template - value: db2_bind_plan + value: db2_bind_plan types: - name: "LOAD" - name: "DBRM" @@ -269,7 +269,7 @@ activities: steps: - name: SCAN_JCL short_name: SCAN_JCL - description: | + description: | This step loops over all JCL members and performs an JCL Expert scan is_artifact: True types: @@ -313,3 +313,59 @@ activities: - key: "template" value: "cics_cmci_prog_update" is_artifact: True + + - name: DEPLOY_ZOS_CONNECT + short_name: DEPLOY_ZOS_CONNECT + description: | + This activity deals with IBM z/OS Connect artifacts + actions: + - name: RESTORE_TO_USS + description: | + Restores the war file to Unix System Services + types: + - name: "war" + tags: + - zosconnect_copy + is_artifact: True + steps: + - name: USS_ARCHIVE + - name: USS_COPY + - name: USS_RESTORE + plan_tags: + - restore + - never + - name: CONFIG_FILES + description: | + Process and deploy z/OS Connect configuration files with variable substitution + steps: + - name: CREATE + properties: + - key: "template" + value: "template" + - key: "var_template_name" + value: "template_name_zosconnect_config" + loop: + loop_query: "wd_query[[ current_plan_step.artifacts[].name ]]" + loop_var: "api_name" + types: + - name: "war" + tags: + - zosconnect_config + is_artifact: True + + - name: ZOS_CONNECT_SERVER + description: | + Refresh z/OS Connect config and applications via a modify command + steps: + - name: REFRESH_CONFIG #"Refresh z/OS Config" + properties: + - key: "template" + value: "system_command" + - key: "var_system_command" + value: "system_command_refresh_config" + - name: REFRESH_APP #"Refresh z/OS Applications" + properties: + - key: "template" + value: "system_command" + - key: "var_system_command" + value: "system_command_refresh_apps" diff --git a/WaziDeploy/zDeploy/deployment-configuration/global/global_initialization.yml b/WaziDeploy/zDeploy/deployment-configuration/global/global_initialization.yml index 7b656ce5..85e77108 100644 --- a/WaziDeploy/zDeploy/deployment-configuration/global/global_initialization.yml +++ b/WaziDeploy/zDeploy/deployment-configuration/global/global_initialization.yml @@ -14,6 +14,7 @@ include_middleware_cfg: files_list: - "{{ deploy_cfg_home }}/deployment-configuration/global/cics_config.yml" - "{{ deploy_cfg_home }}/deployment-configuration/global/db2_config.yml" + - "{{ deploy_cfg_home }}/deployment-configuration/global/zos_connect.yml" files_must_exist: true # reference to global deployment configurations and capabilities diff --git a/WaziDeploy/zDeploy/deployment-configuration/global/types_pattern_mapping.yml b/WaziDeploy/zDeploy/deployment-configuration/global/types_pattern_mapping.yml index 0c3684e8..a893cc05 100644 --- a/WaziDeploy/zDeploy/deployment-configuration/global/types_pattern_mapping.yml +++ b/WaziDeploy/zDeploy/deployment-configuration/global/types_pattern_mapping.yml @@ -79,6 +79,14 @@ types: directory_backup: "{{ uss_root }}/sh/back/" dest_mode: 0777 artifact_mode: 0755 + - type: "WAR" + pattern: .*\.WAR$ + uss: + dest: '{{zos_connect_root}}/apps' + backup_dest: '{{zos_connect_root}}/backup/apps' + mode: 0755 + mode: 0777 + is_binary: True type_dbrm_temp: - type: "DBRM" diff --git a/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml b/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml new file mode 100644 index 00000000..49bc643e --- /dev/null +++ b/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml @@ -0,0 +1,25 @@ +template_name_zosconnect_config: + src: '{{ deploy_cfg_home }}/deployment-configuration/templates/zos_connect_app_config.xml.j2' + dest: '{{ zos_connect_root }}/configDropins/overrides/{{api_name}}.xml' + mode: 0755 + delegate: False + + +# System commands for z/OS Connect server management +system_command_start_server: + cmd: 'S {{zos_connect_job_name}}' + verbose: false + wait_time_s: 5 + wait: true + +system_command_refresh_config: + cmd: 'MODIFY {{zos_connect_job_name}},REFRESH,CONFIG' + verbose: false + wait_time_s: 3 + wait: true + +system_command_refresh_apps: + cmd: 'MODIFY {{zos_connect_job_name}},REFRESH,APPS' + verbose: false + wait_time_s: 3 + wait: true \ No newline at end of file diff --git a/WaziDeploy/zDeploy/deployment-configuration/templates/zos_connect_app_config.xml.j2 b/WaziDeploy/zDeploy/deployment-configuration/templates/zos_connect_app_config.xml.j2 new file mode 100644 index 00000000..adc20c45 --- /dev/null +++ b/WaziDeploy/zDeploy/deployment-configuration/templates/zos_connect_app_config.xml.j2 @@ -0,0 +1,3 @@ + + + diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml index 104dff50..5e806f40 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml @@ -41,6 +41,11 @@ default_db2_qualifier: "QUAL" default_db2_subsys: "DBC1" default_db2_plan_pklist: "*.CBSAPK.*" default_db2_action: "REPLACE" +# z/OS Connect +zos_connect_root: "/var/zosconnect/servers/acceptance/wazideploy-cics" +zos_connect_job_name: "BAQSERV1" +zosconnect_http_port: 9080 + # load shared configuration include_global_config: diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml index 1b71b4ea..2671d574 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml @@ -43,6 +43,11 @@ default_db2_subsys: "DBC1" default_db2_plan_pklist: "*.CBSAPK.*" default_db2_action: "REPLACE" +# z/OS Connect +zos_connect_root: "/var/zosconnect/servers/integration/wazideploy-cics" +zos_connect_job_name: "BAQSERV2" +zosconnect_http_port: 9082 + # load shared configuration include_global_config: files_list: diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml index 84ef64d2..81b3fe53 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml @@ -43,6 +43,11 @@ default_db2_subsys: "DBC1" default_db2_plan_pklist: "*.CBSAPK.*" default_db2_action: "REPLACE" +# z/OS Connect +zos_connect_root: "/var/zosconnect/servers/production/wazideploy-cics" +zos_connect_job_name: "BAQSERV3" +zosconnect_http_port: 9083 + # load shared configuration include_global_config: files_list: diff --git a/WaziDeploy/zDeploy/environment-configuration/python/README.md b/WaziDeploy/zDeploy/environment-configuration/python/README.md index caf2a5b6..5c172d8b 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/README.md +++ b/WaziDeploy/zDeploy/environment-configuration/python/README.md @@ -1,39 +1,52 @@ -# README +# README This folder contains environment files that are passed to wazideploy-deploy for the Wazi Deploy Python translators. -They contain the default values for each environment, such as, default target HLQ, CICS or DB2 subsystem information. +They contain the default values for each environment, such as default target HLQ, CICS, DB2, and z/OS Connect subsystem information. -As a design principle of this sample configuration, the environment files do not contain the full configuration of the WD Python building block variables. Instead it introduces a set of variables that are prefixed with `default_`, that are referenced in the [global configuration files](../../deployment-configuration/global/) +As a design principle of this sample configuration, the environment files do not contain the full configuration of the WD Python building block variables. Instead, they introduce a set of variables that are prefixed with `default_`, which are referenced in the [global configuration files](../../deployment-configuration/global/). -The environment YAML files in this directory serve as templates for defining environment-specific default values used during deployment with Wazi Deploy. They allow deployment administrators to specify key parameters—such as dataset qualifiers, CICS and DB2 subsystem information, and other environment-dependent settings. +The environment YAML files in this directory serve as templates for defining environment-specific default values used during deployment with Wazi Deploy. They allow deployment administrators to specify key parameters—such as dataset qualifiers, CICS, DB2, and z/OS Connect subsystem information, and other environment-dependent settings. By using variables (often prefixed with `default_`), these files enable flexible overrides and integration with global configuration files and potential application overrides. -| Variable Name | Description / Purpose | Example Value | -|------------------------- |------------------------------------------------------------------------------------------------------|----------------------------------| -| application | Application name | to be provided via extra vars | -| hlq | High-level qualifier for datasets (can be overridden via extra vars, sets default for environment) | `WDEPLOY.INT` | -| uss_root | Root directory for USS operations (can be overridden via extra vars, sets default for environment) | `/tmp/wazi-deploy` | -| deploy_cfg_home | Path to deployment configuration home - where this repository is located (can be overridden via extra vars, sets default for environment) | `/var/wazi-deploy-config-sample/` | -| default_cics_user | Default CICS user | `IBMUSER` | -| default_cics_password | Default CICS password var (the variable that contains the password) | `default_cics_password_var` | -| default_cics_context | Default CICS context/region | `CICS01` | -| default_cmci_host | Default CMCI (CICS Management Client Interface) hostname | `127.0.0.1` | -| default_cmci_port | Default CMCI (CICS Management Client Interface) port | `1490` | -| default_cmci_scheme | Default CMCI (CICS Management Client Interface) scheme | `https` | -| default_csd_group | Default CMCI (CICS Management Client Interface) group | `DEFAULT` | -| default_cics_cmci_action | Default CICS CMCI action | `NEWCOPY` | -| default_db2_sdsnload | Default DB2 SDSNLOAD library | `DBC0CFG.DB2.V12.SDSNLOAD` | -| default_pkg_jobcard | Default job card for DB2 package bind jobs | `BINDPKG JOB ...` | -| default_plan_jobcard | Default job card for DB2 plan bind jobs | `BINDPLA JOB ...` | -| default_db2_sqlid | Default DB2 sqlid | `IBMUSER` | -| default_db2_package | Default DB2 package | `DEFAULT` | -| default_db2_plan | Default DB2 plan | `DEFAULT` | -| default_db2_qualifier | Default DB2 qualifier | `QUAL` | -| default_db2_subsys | Default DB2 sub-system | `DBC1` | -| default_db2_plan_pklist | Default DB2 plan packge list | `*.CBSAPK.*` | -| default_db2_action | Default DB2 action | `REPLACE` | +| Variable Name | Description / Purpose | Example Value | +|------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------| +| application | Application name | to be provided via extra vars | +| hlq | High-level qualifier for datasets (can be overridden via extra vars, sets default for environment) | `WDEPLOY.INT` | +| uss_root | Root directory for USS operations (can be overridden via extra vars, sets default for environment) | `/tmp/wazi-deploy/int` | +| deploy_cfg_home | Path to deployment configuration home - where this repository is located (can be overridden via extra vars, sets default for environment) | `/var/wazi-deploy-config-sample/` | +| **CICS Configuration** | | | +| default_cics_user | Default CICS user | `IBMUSER` | +| default_cics_password | Default CICS password (the variable that contains the password) | `sys1` or `default_cics_password_var`| +| default_cics_context | Default CICS context/region | `CICS01` | +| default_cmci_host | Default CMCI (CICS Management Client Interface) hostname | `127.0.0.1` | +| default_cmci_port | Default CMCI (CICS Management Client Interface) port | `1490` | +| default_cmci_scheme | Default CMCI (CICS Management Client Interface) scheme | `http` or `https` | +| default_csd_group | Default CSD (CICS System Definition) group | `DEFAULT` | +| default_cics_cmci_action | Default CICS CMCI action | `NEWCOPY` | +| default_env_cics_sdfhload | Default CICS SDFHLOAD library | `CICSTS.V5R5.CICS.SDFHLOAD` | +| default_env_cics_csd | Default CICS CSD dataset | `CICSGUSR.CICS.CICS01.DFHCSD` | +| default_cmci_insecure | Whether to allow insecure CMCI connections | `False` | +| default_cmci_cert | Path to CMCI certificate file | `""` | +| default_cmci_key | Path to CMCI key file | `""` | +| **DB2 Configuration** | | | +| default_db2_sdsnload | Default DB2 SDSNLOAD library | `DBC0CFG.DB2.V12.SDSNLOAD` | +| default_pkg_jobcard | Default job card for DB2 package bind jobs | `BINDPKG JOB 'WD-PKGBIND',...` | +| default_plan_jobcard | Default job card for DB2 plan bind jobs | `BINDPLA JOB 'WD-PLANBIND',...` | +| default_db2_sqlid | Default DB2 SQL ID | `IBMUSER` | +| default_db2_package | Default DB2 package | `DEFAULT` | +| default_db2_plan | Default DB2 plan | `DEFAULT` | +| default_db2_qualifier | Default DB2 qualifier | `QUAL` | +| default_db2_subsys | Default DB2 subsystem | `DBC1` | +| default_db2_plan_pklist | Default DB2 plan package list | `*.CBSAPK.*` | +| default_db2_action | Default DB2 action | `REPLACE` | +| **z/OS Connect Configuration** | | | +| zos_connect_root | Root directory for z/OS Connect server configuration | `/var/zosconnect/servers/integration/wazideploy-cics` | +| zos_connect_job_name | Job name for z/OS Connect server | `BAQSERV2` | +| zosconnect_http_port | HTTP port for z/OS Connect server | `9082` | +| **JCL Expert Configuration** | | | +| run_jcl_expert | Whether to run JCL Expert validation during deployment | `False` | These variables allow deployment administrators to define and override environment-specific defaults for each deployment target. \ No newline at end of file From 1f73f9bcbb6f66d92e535a388610cf5e07fffeb1 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 19 Jun 2026 09:49:15 +0200 Subject: [PATCH 2/5] Follow variables prefix patterns Signed-off-by: Dennis Behm --- .../global/zos_connect.yaml | 16 ++++++++++++---- .../application-overrides/README.md | 2 ++ .../python/EOLEB7-Acceptance.yml | 8 +++++--- .../python/EOLEB7-Integration.yml | 6 +++--- .../python/EOLEB7-Production.yml | 5 ++--- 5 files changed, 24 insertions(+), 13 deletions(-) diff --git a/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml b/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml index 49bc643e..cbdf8fcc 100644 --- a/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml +++ b/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml @@ -1,25 +1,33 @@ +################################################################################# +# This file configures the z/OS Connect actions for the deployment +################################################################################# + +zos_connect_sys_def: + root: "{{ app_zos_connect_root if app_zos_connect_root is defined and app_zos_connect_root else default_zos_connect_root }}" + job_name: "{{ app_zos_connect_job_name if app_zos_connect_job_name is defined and app_zos_connect_job_name else default_zos_connect_job_name }}" + template_name_zosconnect_config: src: '{{ deploy_cfg_home }}/deployment-configuration/templates/zos_connect_app_config.xml.j2' - dest: '{{ zos_connect_root }}/configDropins/overrides/{{api_name}}.xml' + dest: '{{ zos_connect_sys_def.root }}/configDropins/overrides/{{api_name}}.xml' mode: 0755 delegate: False # System commands for z/OS Connect server management system_command_start_server: - cmd: 'S {{zos_connect_job_name}}' + cmd: 'S {{ zos_connect_sys_def.job_name }}' verbose: false wait_time_s: 5 wait: true system_command_refresh_config: - cmd: 'MODIFY {{zos_connect_job_name}},REFRESH,CONFIG' + cmd: 'MODIFY {{ zos_connect_sys_def.job_name }},REFRESH,CONFIG' verbose: false wait_time_s: 3 wait: true system_command_refresh_apps: - cmd: 'MODIFY {{zos_connect_job_name}},REFRESH,APPS' + cmd: 'MODIFY {{ zos_connect_sys_def.job_name }},REFRESH,APPS' verbose: false wait_time_s: 3 wait: true \ No newline at end of file diff --git a/WaziDeploy/zDeploy/environment-configuration/application-overrides/README.md b/WaziDeploy/zDeploy/environment-configuration/application-overrides/README.md index d7ec7e8a..c629a323 100644 --- a/WaziDeploy/zDeploy/environment-configuration/application-overrides/README.md +++ b/WaziDeploy/zDeploy/environment-configuration/application-overrides/README.md @@ -29,5 +29,7 @@ The `EOLEB7-Integration.yml` file defines application-level configuration settin | app_cmci_scheme | CICS schema http/https | | app_cmci_host | CICS CMCI host | | app_cmci_port | CICS CMCI port | +| app_zos_connect_root | z/OS Connect server USS root directory path | +| app_zos_connect_job_name | z/OS Connect server job name for management commands | | app_jcl_text_subs_patterns | List of JCL text substitution patterns for JCL text substitutions, such as replacing `@PGMLIB` with the value of `{{ hlq }}`. | diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml index 5e806f40..2a7ca7af 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml @@ -30,6 +30,7 @@ default_env_cics_csd: "CICSGUSR.CICS.CICS01.DFHCSD" default_cmci_insecure: False default_cmci_cert: "" default_cmci_key: "" + # Db2 default_db2_sdsnload: "DBC0CFG.DB2.V12.SDSNLOAD" default_pkg_jobcard: "BINDPKG JOB 'WD-PKGBIND',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID" @@ -41,10 +42,11 @@ default_db2_qualifier: "QUAL" default_db2_subsys: "DBC1" default_db2_plan_pklist: "*.CBSAPK.*" default_db2_action: "REPLACE" + # z/OS Connect -zos_connect_root: "/var/zosconnect/servers/acceptance/wazideploy-cics" -zos_connect_job_name: "BAQSERV1" -zosconnect_http_port: 9080 +default_zos_connect_root: "/var/zosconnect/servers/acceptance/wazideploy-cics" +default_zos_connect_job_name: "BAQSERV1" +default_zosconnect_http_port: 9080 # load shared configuration diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml index 2671d574..af1dfd3a 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml @@ -44,9 +44,9 @@ default_db2_plan_pklist: "*.CBSAPK.*" default_db2_action: "REPLACE" # z/OS Connect -zos_connect_root: "/var/zosconnect/servers/integration/wazideploy-cics" -zos_connect_job_name: "BAQSERV2" -zosconnect_http_port: 9082 +default_zos_connect_root: "/var/zosconnect/servers/integration/wazideploy-cics" +default_zos_connect_job_name: "BAQSERV2" +default_zosconnect_http_port: 9082 # load shared configuration include_global_config: diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml index 81b3fe53..a8b3eac0 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Production.yml @@ -44,9 +44,8 @@ default_db2_plan_pklist: "*.CBSAPK.*" default_db2_action: "REPLACE" # z/OS Connect -zos_connect_root: "/var/zosconnect/servers/production/wazideploy-cics" -zos_connect_job_name: "BAQSERV3" -zosconnect_http_port: 9083 +default_zos_connect_root: "/var/zosconnect/servers/production/wazideploy-cics" +default_zos_connect_job_name: "BAQSERV3" # load shared configuration include_global_config: From 7b5eccc78ad57193628f1467e3bb9b6d5b1e13c2 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 19 Jun 2026 09:52:47 +0200 Subject: [PATCH 3/5] Remove VALIDATION.md from branch --- .../deployment-configuration/VALIDATION.md | 145 ------------------ 1 file changed, 145 deletions(-) delete mode 100644 WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md diff --git a/WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md b/WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md deleted file mode 100644 index f2af1491..00000000 --- a/WaziDeploy/zDeploy/deployment-configuration/VALIDATION.md +++ /dev/null @@ -1,145 +0,0 @@ -# YAML Schema Validation - -This directory contains tools for validating the `deployment-method.yml` file against its JSON schema. - -## Prerequisites - -### Python Virtual Environment - -The VS Code tasks are configured to use the Python virtual environment at: -``` -/Users/dennisbehm/devops-venv/bin/activate -``` - -Install the required Python packages in the virtual environment: - -```bash -source /Users/dennisbehm/devops-venv/bin/activate -pip install pyyaml jsonschema -``` - -Or use the VS Code task: **"Install Python Dependencies for YAML Validation"** (automatically activates the venv) - -## Validation Methods - -### 1. VS Code Tasks (Recommended) - -Three VS Code tasks are available in the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`): - -#### Task: "Validate Deployment Method YAML Schema" -- **Usage**: Open any YAML file and run this task -- **Description**: Validates the currently open file against the schema -- **Best for**: Validating any YAML file in the workspace - -#### Task: "Validate Deployment Method YAML (Fixed Path)" -- **Usage**: Run from anywhere in the workspace -- **Description**: Always validates `deployment-method.yml` specifically -- **Best for**: Quick validation of the main deployment method file - -#### Task: "Install Python Dependencies for YAML Validation" -- **Usage**: Run once to install dependencies -- **Description**: Installs `pyyaml` and `jsonschema` packages - -### 2. Command Line - -Run the validation script directly with the virtual environment: - -```bash -# Activate the virtual environment first -source /Users/dennisbehm/devops-venv/bin/activate - -# From the deployment-configuration directory -python3 validate_schema.py \ - deployment-method.yml \ - ../../Schemas/dep-method-schema.json - -# From the workspace root -python3 WaziDeploy/zDeploy/deployment-configuration/validate_schema.py \ - WaziDeploy/zDeploy/deployment-configuration/deployment-method.yml \ - WaziDeploy/Schemas/dep-method-schema.json -``` - -### 3. GitHub Actions / CI Pipeline - -For automated validation in CI/CD pipelines, see the examples in the main repository documentation. - -## Output Examples - -### Successful Validation -``` -====================================================================== -YAML Schema Validation -====================================================================== -✓ Loaded YAML file: deployment-method.yml -✓ Loaded schema file: ../../Schemas/dep-method-schema.json - -✅ YAML validation successful! - File: deployment-method.yml - Schema: ../../Schemas/dep-method-schema.json -====================================================================== -``` - -### Failed Validation -``` -====================================================================== -YAML Schema Validation -====================================================================== -✓ Loaded YAML file: deployment-method.yml -✓ Loaded schema file: ../../Schemas/dep-method-schema.json - -❌ Validation failed with 2 error(s): - -Error 1: - Location: metadata - Message: 'name' is a required property - Validator: required - -Error 2: - Location: activities → 0 → actions - Message: [] is too short - Validator: minItems - -====================================================================== -``` - -## Schema Reference - -The validation uses the JSON Schema Draft 7 specification: -- **Schema Location**: `WaziDeploy/Schemas/dep-method-schema.json` -- **Schema URL**: https://github.com/IBM/dbb/raw/refs/heads/main/Wazi_Deploy/Schemas/dep-method-schema.json - -## Troubleshooting - -### Python Not Found -If you get a "python3: command not found" error: -- Install Python 3.7 or later -- On macOS: `brew install python3` -- On Linux: `sudo apt-get install python3` - -### Missing Dependencies -If you get import errors, install packages in the virtual environment: -```bash -source /Users/dennisbehm/devops-venv/bin/activate -pip install pyyaml jsonschema -``` - -### Permission Denied -Make the script executable: -```bash -chmod +x validate_schema.py -``` - -## Integration with VS Code - -The validation script is integrated with VS Code through tasks defined in `.vscode/tasks.json`. You can: - -1. Run tasks via Command Palette: `Tasks: Run Task` -2. Bind tasks to keyboard shortcuts in `keybindings.json` -3. Add tasks to the status bar with extensions like "Task Runner" - -## Additional Resources - -- [JSON Schema Documentation](https://json-schema.org/) -- [Wazi Deploy Documentation](https://www.ibm.com/docs/en/wazi-deploy) -- [PyYAML Documentation](https://pyyaml.org/) -- [jsonschema Python Package](https://python-jsonschema.readthedocs.io/) \ No newline at end of file From 83b44a53de79e36680cbd53857e00c8619c7f3e3 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 19 Jun 2026 09:54:15 +0200 Subject: [PATCH 4/5] Remove port Signed-off-by: Dennis Behm --- .../environment-configuration/python/EOLEB7-Acceptance.yml | 2 -- .../environment-configuration/python/EOLEB7-Integration.yml | 1 - 2 files changed, 3 deletions(-) diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml index 2a7ca7af..85510a5b 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Acceptance.yml @@ -46,8 +46,6 @@ default_db2_action: "REPLACE" # z/OS Connect default_zos_connect_root: "/var/zosconnect/servers/acceptance/wazideploy-cics" default_zos_connect_job_name: "BAQSERV1" -default_zosconnect_http_port: 9080 - # load shared configuration include_global_config: diff --git a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml index af1dfd3a..5fad6f46 100644 --- a/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml +++ b/WaziDeploy/zDeploy/environment-configuration/python/EOLEB7-Integration.yml @@ -46,7 +46,6 @@ default_db2_action: "REPLACE" # z/OS Connect default_zos_connect_root: "/var/zosconnect/servers/integration/wazideploy-cics" default_zos_connect_job_name: "BAQSERV2" -default_zosconnect_http_port: 9082 # load shared configuration include_global_config: From 911718f51eceb424c52ba1fbd94d9a90e1cf8cf5 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 19 Jun 2026 10:12:43 +0200 Subject: [PATCH 5/5] Apply correct file extension Signed-off-by: Dennis Behm --- .../global/{zos_connect.yaml => zos_connect.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename WaziDeploy/zDeploy/deployment-configuration/global/{zos_connect.yaml => zos_connect.yml} (100%) diff --git a/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml b/WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yml similarity index 100% rename from WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yaml rename to WaziDeploy/zDeploy/deployment-configuration/global/zos_connect.yml