pshregistry-parser

Platform.sh Registry Parser

This is a simple library for parsing the Platform.sh registry. It provides access to a subset of Registry properties for each image, and it can be used to generate valid and up-to-date configuration YAML files for Platform.sh written in Node.js. It accesses data in a registry.json to generate those files.

Note: At this stage, the library requires a local copy of registry.json to be defined in order to work. Ultimately, there will be no local registry file it reads from, instead reading from a remote, regularly-updating source in GitLab.

Usage Example

This is an early stage of the registry project.

At this point, common actions like adding a newly supported version to an existing image requires you to manually add that new version to the <image>.versions.supported attribute in the registry.json file.

You can find the current up-to-date version of this file in the public docs repo located here: https://github.com/platformsh/platformsh-docs/blob/master/src/registry/images/registry.json

Generating example configuration files

The library creates example YAML files that fall into three main categories:

• commented: Full configuration file used in a project, including heavy commenting. For example, for Elasticsearch,

  # The name given to the Elasticsearch service (lowercase alphanumeric only).
  mysearch:
    # The type of your service (elasticsearch), which uses the format
    # 'type:version'. Be sure to consult the Elasticsearch documentation
    # (https://docs.platform.sh/configuration/services/elasticsearch.html#supported-versions)
    # when choosing a version. If you specify a version number which is not available,
    # the CLI will return an error.
    type: elasticsearch:7.2
    # The disk attribute is the size of the persistent disk (in MB) allocated to the service.
    disk: 256
  

• full: Full configuration file used in a project. For the Elasticsearch .platform.app.yaml,

  relationships:
    elasticsearch: "mysearch:elasticsearch"
  

• snippet: Partial configuration file. Single-line for that image so that it could be used to append to another file if we ever want to have tools that generate complete configuration files for the user. For the Elasticsearch .platform.app.yaml snippet,

    elasticsearch: "mysearch:elasticsearch"
  

Each of these files for every image in a Registry object is generated from the write() method:

// updateConfigs.js
const psh = require("pshregistry-parser");

var registryLocation = "src/registry/images/registry.json";

var registry = new RegistryParser(registryLocation);
registry.write();

but you can also write files for individual images (i.e. Elasticsearch) with

cg.write("elasticsearch");

Filenames use the convention <image_name>.<config_file>.yaml. Therefore, the command cg.write("elasticsearch") would generate

saveDir/
    examples/
        commented/
            elasticsearch.app.yaml
            elasticsearch.services.yaml
        full/
            elasticsearch.app.yaml
            elasticsearch.services.yaml
        snippet/
            elasticsearch.app.yaml
            elasticsearch.services.yaml

content.json

Depending on your use case, you may not want to install this library as a dependency for your project, and instead point to another repository that serves the generated example configuration YAMLs as a resource. In order to facilitate your ability to do so, each examples subdirectory contains a file called content.json which lists all of the example files in that subdirectory. For example, examples/commented/content.json could include the object:

{
  "files": [
    "elasticsearch.app.yaml",
    "elasticsearch.services.yaml",
    "golang.app.yaml",
    "kafka.app.yaml",
    "kafka.services.yaml",
    "redis.app.yaml",
    "redis.services.yaml",
    "mariadb.app.yaml",
    "mariadb.services.yaml",
    "network-storage.app.yaml",
    "network-storage.services.yaml",
    "varnish.app.yaml",
    "varnish.routes.yaml",
    "varnish.services.yaml",
    "mysql.app.yaml",
    "mysql.services.yaml",
    "redis-persistent.app.yaml",
    "redis-persistent.services.yaml"
  ]
}

content.json files are not created when single images are passed to write(), only when files are written for every image in the Registry.

Save Location

You can specify the save location for the generated YAML files with a second parameter to RegistryParser()

const psh = require("pshregistry-parser");

var registryLocation = "src/registry/images/registry.json";
var saveLocation = "myfiles/examples/"

var registry = new RegistryParser(registryLocation, saveLocation);
registry.write();

If a directory is not specfied, the library will assume that all files should be generated in the same directory as registry.json. If examples or any of its subdirectories do not exist, they will be created.

Accessing images

Each Registry image is an instance of a child of an Image object, and is accessible directly from the config generator instance through the images property. For example, registry.images["php"] returns

Runtime {
  indent: '    ',
  description: 'PHP service for Platform.sh.',
  repo_name: 'php',
  disk: false,
  docs:
   { relationship_name: null,
     service_name: null,
     url: '/languages/php.html' },
  endpoint: null,
  min_disk_size: null,
  name: 'PHP',
  runtime: true,
  type: 'php',
  supported: [ '7.1', '7.2', '7.3' ],
  deprecated: [ '5.4', '5.5', '5.6', '7.0' ],
  recommended: '7.3',
  supportedHTML: '<ul><li>7.1</li><li>7.2</li><li>7.3</li></ul>',
  supportedString: '7.1, 7.2, 7.3',
  deprecatedHTML: '<ul><li>5.4</li><li>5.5</li><li>5.6</li><li>7.0</li></ul>',
  deprecatedString: '5.4, 5.5, 5.6, 7.0',
  config:
   { app:
      { commented:
         '# The runtime the application uses. The \'type\' key defines the base container\n# image that will be used to run the application. There is a separate base\n# container image for each primary language for the application,\n# in multiple versions. Check the PHP documentation\n# (https://docs.platform.sh/languages/php.html#supported-versions)\n# to find the supported versions for the \'php\' type.\ntype: php:7.3',
        full: 'type: php:7.3',
        snippet: 'type: php:7.3' },
     routes: { commented: '', full: '', snippet: '' },
     services: { commented: '', full: '', snippet: '' } } }

PHP is a Runtime instance, whereas MariaDB is a Service instance. They each contain the same properties, some of which are built by pshregistry-parser and others will be a public subset of properties in the generated Registry. They only differ in the way they construct the template strings that are placed in their example configuration files.

Note: In the above example, registry.images.php is also valid, but not recommended generally. The keys of image objects use their type by default, and for certain images (i.e, "chrome-headless", "network-storage", "oracle-mysql", "persistent-redis") their type key includes a hyphen, which is not allowed for directly accessing object properties with registry.images.<image_type>.

The generated Registry will likely continue to use 'type' for image keys, so no workaround has been included to convert these examples into snakeCase. Feel free to use the other form if your use is restricted to a few images that you know will not run into this problem, but if you are going to be using every image that will include the examples above, stick to registry.images["image_type"].property.

There are certain special cases where configuration files for a service are very different than others, and in those cases the property for that image is an instance of its own class (e.g., Varnish, NetworkStorage).

Recommended versions

For each example configuration YAML file, a "recommended" supported version is chosen and used in each file where a version must be specified. In this case, the newest supported release is considered the recommended version, and is determined with registry.images["elasticsearch"].recommended.

Future work

1. Use other places in the docs

pshregistry-parser functions for accessing formatted image versions that are not currently used. They return the content that will be useful for filling out other areas of the docs with version information (i.e. Getting Started tables and Supported/Deprecated sections of each image page).

registry.images["elasticsearch"].supportedString is a raw string of supported versions ("6.5, 7.2"), whereas registry.images["elasticsearch"].supportedHTML is an HTML unordered list ("<ul><li>6.5</li><li>7.2</li></ul>"). deprecatedString and deprecatedHTML are available as well.

1. Generating the registry

Right now we will have to edit the registry.json by hand, but ideally this library will point at a "ground truth" repo somewhere else (that updates regularly) to get its data. When that happens, the registry.json file will be eliminated from docs altogether, and calling write() will also call an update() command to the ground truth registry.json in its final repo, sync up, and write the files using that data rather than a local source.