Using Z Open Editor on GitHub Codespaces

GitHub Codespaces is built on VS Code's Dev Container technology, which enables developers to write their code in a container that runs either locally or remotely. VS Code can then connect to that container and enable access to the folders inside the container. It also installs VS Code extensions from the marketplace in the container, so the extension can work with the files located there. In addition to connect the rich VS Code client to the container, it also supports to run the VS Code editor client in the browser where a VS Code Server, which runs inside the container, renders the editor in browser. See Developing inside a Container in the VS Code documentation for more details on the underlying technology. To learn everything about GitHub Code Spaces go to the official Documentation.

When using GitHub codespaces, the container runs in Microsoft's Azure Cloud and gets dynamically created for your account on a virtual machine managed by Azure. As a user, you need not procure a development machine that can run containers; all you need is browser and a GitHub account with Git projects to write code. You can use the same container specification, the devcontainer files that you are using for Codespaces for local or on-premises deployment of these containers as well, giving you great flexibility to decide where to run your remote development environments. This enables you to chose between paying for Cloud-based compute resources or to manage your own infrastructure of virtual machines in which the containers can run.

This architecture is different than Red Hat® OpenShift® Dev Spaces, which comes with pros and cons:

• Codespaces runs in a container and not Kubernetes: The biggest difference is that Codespaces runs in a container that can be modified by the developer at runtime. Developers can install additional software and update components. You can even make devcontainer configuration changes on the fly and let VS Code recreate the container with the new components and settings from within VS Code. OpenShift Dev Spaces workspaces run in Kubernetes as immutable containers that cannot be modified by the developer. For installing additional or updated software, Dev Spaces requires building and publishing a new image from a dockerfile. The advantage is that these containers are more secure, because developers cannot randomly install software that was not reviewed and approved by your organization. This also ensures that all developers in a team work with the exact same versions and configuration settings, avoiding the effect "it runs in my container".

• Codespaces is only available at github.com: OpenShift Dev Spaces can be installed wherever OpenShift runs, which includes on-premises deployments using x86 and s390x Linux on Z platforms, deployments at all the major Cloud providers such as IBM Cloud®, AWS, or Azure, and even on personal laptops or developer machine with OpenShift Local. GitHub Codespaces is only available on github.com and not available for GitHub Enterprise for on-premises deployments. However, you can use it from a private organization and you can configure it with access to your company network using OpenVPN technology as described below in Connect to a z/OS system using a VPN.

• Codespaces configuration files are portable to custom containers: The devfiles you create for OpenShift DevSpaces workspaces can only be used at the moment, in an OpenShift Dev Spaces deployment. However, the Codespaces devcontainer files and dockerfiles can generally be used interchangeably between Codespaces and personal containers to run locally on your developer machine or on on-premises virtual machines.

In the Z Open Editor Samples Git repository, a special branch called "devcontainer" is provided that contains examples for Codespaces configuration files that you can try. As described in the Quickstart section of Overview to using Cloud and Browser-based platforms, you can easily start a Codespaces workspace with the samples repository loaded and Z Open Editor and other extensions preloaded by clicking or copy-pasting a simple URL: Sample repository

If you examine this URL carefully, you see various parameters that specify what to load into the workspace. When you click the link, you see all the parameters in a Web form to change or just confirm. The parameters provide the location and type of the virtual machine to be used, the GitHub repository to load identified with its global integer ID, the branch of the repository to check out, as well as the location of the devcontainer specification file to use. The last parameter enables you to manage several alternative devcontainer specification files in the same branch, but loads different development configurations on demand if needed. In the sample repository, you also find several examples inside this folder organized in sub-directories, which is discussed throughout this documentation.

To examine the sample devcontainer specification file provided with the Z Open Editor samples, open the following file from the Git repository.

The file is located in a folder called ".devcontainer", together with a Bash script called "installZowe.sh". Inside the JSON file, you can see various configuration settings:

• "image": is the base image for the container to be loaded. The recommendation is, if in doubt about which image to use, list the named "universal" as the default. It is documented in the devcontainers. However, there are many special images available as well. Because Z Open Editor requires a Java™ 17 runtime, which was selected in the devcontainer file a Java base image. For the full list of available images, see here.

• "features": in addition to the software available on the base image, you can easily specify additional features you want without the need to create a custom container image using a dockerfile. You can just specify features that you want to see, added by name with parameters and loaded dynamically into the container. The first time you load the container, startup of the workspace takes a little bit longer to load the features, but then as a result the container caches and loads up much faster at the next startup. In the example, you see that the JAVA is configured with an additional Maven option, because the Z Open Editor preprocessor samples provided in the repository comes with a Maven Java project. Install node.js, which is required for Zowe™ CLI and install Ansible® for the z/OS® Ansible playbooks provided in the repository. After the Codespaces workspace is up, open a Terminal window and check if all the components are available, e.g. run ansible --version or mvn -version to see version information. The list of available features is absolutely massive, as you can see on the reference page here.

• "updateContentCommand": can provide a command to load additional content into the image that is not available as a feature. In this case run the "installZowe.sh" script, which simply uses npm to install Zowe CLI and the IBM® RSE API for Zowe CLI plugin.

• "customizations": contains settings to configure VS Code, Codespaces, as well as the VS Code extensions that can be preloaded into the devcontainer. In the example, you see all the recommended extensions are loaded to work with Z Open Editor, which includes Zowe Explorer, Red Hat's YAML extension to edit ZAPP files, Red Hat's Ansible extension, as well as the Java development pack to build the Java samples in the repository mentioned above.

When you load the Z Open Editor sample workspace into Codespaces with the URL listed above. The VS Code starts up in your browser, the sample Git repository gets automatically cloned with the devcontainer branch as specified and loads into VS Code. When you check the list of installed VS Code extensions, you find all the extension listed in the devcontainer.json file ready to go. When you open a Terminal, you can test the installed software, with the command line examples from above you can find everything available as specified.

There a several other ways to configure a devcontainer, including installing additional software with a dockerfile. To learn more about it see the Codespaces documentation.

As GitHub Codespaces runs on github.com and Azure, you need to establish a secure network configuration from your devcontainer to your company's intranet to access mainframe resources with Zowe Explorer and Zowe CLI. To accomplish that connect to your organization using a Virtual Private Network as described in the Connecting to a private network in the Codespaces documentation.

The documentation page links to a Git repository with an example where it is integrated into the Z Open Editor sample repository, to try with the editor and Zowe Explorer. Under .devcontainer/vpn you find another complete example for a devcontainer that does everything the specification in the earlier example does, but also adds the ability to connect to a VPN server. To accomplish that it provides the following additions:

• "Dockerfile": which uses the same base image as the devcontainer specification of the previous example and adds the VPN client software installation instructions.

• "devcontainer.json": refers to the dockerfile, instead to load the resulting image. It also adds "runArgs", "initializeCommand", "postStartCommand" to initialize and start the VPN client through scripts provided in the folder as well.

• "save-config.sh": is a Bash script executed from the devcontainer that sets up the VPN client. The main thing it does is takes your personal OpenVPN configuration stored as a secret in Github under the name "OPENVPN_CONFIG" and serializes it to a temporary file that the VPN client can use to connect. See this example for how the secret looks.

• "start-openvpn.sh": starts the VPN client with the configuration prepared by "save-config.sh". You can always manually rerun this script if the VPN connection drops. The log file for the VPN client is stored in ".devcontainer/vpn/openvpn-tmp/openvpn.log", which you can open from your VS Code workspace to review it for any issues in connection.

Try this example in the devcontainer with the following steps:

• Fork the GitHub repository and checkout or select the branch "devcontainer".

• Receive an ".ovpn" file from your Open VPN administrator.

• In your personal fork on Github.com, go to Settings > Secrets and variables > Codespaces and create a secret named OPENVPN_CONFIG and paste the contents of the ".ovpn" file.

• Create two additional secrets for your Zowe profile credentials: Create the secrets ZOWE_OPT_USER and ZOWE_OPT_PASSWORD with the username and password values that you use with either z/OSMF or RSE API to access your z/OS system.

• Go to the Code tab of your fork and start Codespaces through the <> Code dropdown menu to select the Codespaces tab and New with options from the sub-menu in that tab.

• In the "Create codespace" page, select "Z Open Editor container with VPN" from the Dev container configuration dropdown. Its important to select this option and not use the default devcontainer without the VPN configuration.

• Click Create codespace

• After the workspace is up, create a Zowe Explorer team configuration file to connect to your z/OS system made available through the VPN. Ensure that you use the environment variables "$ZOWE_OPT_USER" and "$ZOWE_OPT_PASSWORD" as values for the "user" and "password" properties in your configuration file. See the details in Using Environment Variables for Authentication in Zowe Explorer and Openshift Dev Workspaces.

If you are using IBM Wazi as Service (Documentation) virtual z/OS server instances (VSI) that run in an IBM Cloud® VPC (Virtual Private Cloud), then this is how you can access your VSIs.

• Create a VPN server for your VPC at this link.

• Configure a Route and attach your security groups to access z/OSMF or RSE API to the VPN server.

• Download the VPN's "Client profile", which is a zip file that contains the ".ovpn" file.

• Paste the contents of the ".ovpn" file as the secret in your Github repository fork.

• Connect as described above.

You can access your Wazi as a Service VSI running in IBM Cloud from your Zowe Explorer running on Azure through a secure VPN tunnel.