Using Z Open Editor on GitHub Codespaces

IBM Z Open Editor, Zowe Explorer and Zowe CLI can run in Microsoft's GitHub Codespaces.

Overview

GitHub Codespaces is built on VS Code's so-called Dev Container technology, which allows developers to write their code in a container that runs either locally or remotely. VS Code can then connect to that container allowing access to 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 connecting with the rich VS Code client to the container, it also supports running the VS Code editor client in the browser where a so-called 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 do not need to procure a development machine that can run containers, but all you need is browser and a GitHub account with Git projects to write code. However, you can use the same container specification that you are using for Codespaces, the devcontainer files, for local or on-premises deployment of these containers as well, giving you great flexibility to decide where to run your remote development environments. Hence, you can chose between paying for Cloud-based compute resources or managing 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 "it runs in my container" effect.
• Codespaces is only available at github.com: OpenShift Dev Spaces can be installed wherever OpenShift runs, which includes on-premises deployments using x86 as well as s390x Linux on Z platforms, deployments at all the major Cloud providers such as IBM Cloud, AWS, or Azure, and even your personal laptop or developer machine with OpenShift Local. GitHub Codespaces is only available on github.com. It is 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 Connecting 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, mostly, be used interchangeably between Codespaces and personal containers running locally on your developer machine or on on-premises virtual machines.

Configuring a sample Z Open Editor workspace

In our Z Open Editor Samples Git repository at https://github.com/IBM/zopeneditor-sample we provide a special branch called "devcontainer" 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 our samples repository loaded and Z Open Editor and other extensions preloaded by clicking or copy-pasting a simple URL:

https://github.com/codespaces/new?skip_quickstart=true&machine=basicLinux32gb&repo=160883618&ref=devcontainer&geo=UsWest&devcontainer_path=.devcontainer%2Fdevcontainer.json

If you examine this URL carefully you see various parameters that specify what should be loaded into the workspace. When you click the link you see all the parameters in a Web form for you 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. That last parameter allows you to manage several alternative devcontainer specification files in the same branch, but load different development configurations on demand if needed. In our sample repository you also find several examples inside this folder organized in sub-directories, which will be discussed throughout this documentation.

To examine that sample devcontainer specification file we provide with our Z Open Editor samples, open the following file from the Git repository: https://github.com/IBM/zopeneditor-sample/blob/devcontainer/.devcontainer/devcontainer.json

As you can see the file is located in a folder called ".devcontainer", together with a bash script called "installZowe.sh". Inside the json file your can see various configuration settings:

• "image": is the base image for the container that should be loaded. The recommendation is, if in doubt about which image to use, to list the so-called universal image as the default. It is documented at https://github.com/devcontainers/images/tree/main/src/universal. However, there are many special images available as well. Because Z Open Editor requires a Java 17 runtime, we selected in our devcontainer file a Java base image. For the full list of available images see here: https://github.com/devcontainers/images/blob/main/README.md
• "features": in addition to the software available on the base image you can easily specify additional features that you want to be available without the need of creating a custom container image using a dockerfile. You can just specify features that you want to see added by name with parameters and they will be 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 the resulting container will be cached and will load up much faster the next startup. In our example you see that we configure Java with an additional Maven option, because our Z Open Editor preprocessor samples provided in our repo come with a Maven Java project. We also install node.js, which is required for Zowe CLI, and we install Ansible for the z/OS Ansible playbooks provided in our repository. Once the Codespaces workspace is up, open a Terminal window and check that 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: https://containers.dev/features.
• "updateContentCommand": can provide a command to load additional content into the image that is not available as a feature. In our case we are running the "installZowe.sh" script, which simply uses npm to install Zowe CLI and the IBM RSE API for Zowe CLI plugin.
• "customizations": contains settings for configuring VS Code, Codespaces, as well as the VS Code extensions that should be preloaded into the devcontainer. In our example, you see we are loading all the recommended extensions for working with Z Open Editor, which includes Zowe Explorer, Red Hat's YAML extension for editing ZAPP files, Red Hat's Ansible extension, as well as the Java development pack for building the Java samples in our repository mentioned above.

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

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

Connecting to a z/OS system using a VPN

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 for accessing mainframe resources with Zowe Explorer and Zowe CLI. You can accomplish that by connecting to your organization using a Virtual Private Network as described in the Connecting to a private network in the Codespaces documentation.

This documentation page links to a Git repository with an example that we have integrated into our sample repository for you to try with Z Open 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": now refers to this dockerfile instead to load the resulting image. It also adds "runArgs", "initializeCommand", "postStartCommand" to initialize and start the VPN client via 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 it taking your personal OpenVPN config stored as a secret in Github under the name "OPENVPN_CONFIG" and serializing it to a temporary file that the VPN client can use to connect. See this example for how the secret needs to look like.
• "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 will be stored in ".devcontainer/vpn/openvpn-tmp/openvpn.log", which you can open from your VS Code workspace to review it for any issues connecting.

You can try this example in our devcontainer with the following steps:

• Fork our GitHub repository at https://github.com/IBM/zopeneditor-sample and checkout/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 called "OPENVPN_CONFIG" and paste the contents of the ".ovpn" file.
• Go to the Code tab of your fork and start Codespaces via the "<> Code" dropdown menu selecting the "Codespaces" tab and "New with options" from the sub-menu in that tab.
• In the "Create codespace" page select in the "Dev container configuration" dropdown the value "Z Open Editor container with VPN". (Important to select and not use the default devcontainer without the VPN configuration.)
• Click "Create codespace"
• Once the workspace is up, create a Zowe Explorer Team Configuration file to connect to your z/OS system made available through the VPN.

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 exactly how you can access your VSIs.

• Create a VPN server for your VPC at https://cloud.ibm.com/infrastructure/network/vpngateways.
• Configure a Route and attach your security groups for accessing z/OSMF or RSE API to the VPN server.
• Download the "Client profile", which is a zip file that contains the ".ovpn" file.
• Paste the contents of the ".ovpn" file as the secret.
• Connect as described above.

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