tc Server Runtime and Template Repository Changes

Important Notice About tc Server Repository Changes

Due to the integration with VMware systems, the backend server hosting the tc Server Runtime and Template repositories is changing.

March 31, 2023 is the shutdown date for the deprecated tc Server Runtime and Template repositories.

This document is intended to provide complete information regarding the changes.

Note: The feature to download tc Runtimes and Templates from a remote repository is not ending. It has been modified to work with Tanzu Network and offers a new option to self-host a repository for customers.

What exactly is changing?

The tcserver command has features to aid in upgrading the tc Runtime version and allows downloading from an Artifactory repository formerly hosted by Pivotal. The Pivotal repository is being shutdown in Q2 of 2023.

In order to access the new VMware Tanzu Network hosted repository, an API Refresh Token must be provided to tc Server. An extra configuration step is needed to use the affected features.

In addition, a new self-hosted repository feature has been added. This allows customers to host their own repository of tc Runtimes and Templates. This could be useful for customers with incoming network traffic restrictions and other needs which prevent the usage of the Tanzu Network repository.

The following tcserver commands are affected by this change:

list-runtimes
get-runtime
list-template
get-template
create - (if runtimes.ondemand=true is configured in tcserver.properties)

The versioning of the tc Runtime is changing due to the way the tc Runtime versions are listed on Tanzu Network. On Tanzu Network the tc Runtime versions do not include the .RELEASE string. Therefore when listing tc Runtimes from Tanzu Network the .RELEASE string will not be displayed.

Version Specific Notices

Versions of tc Server in the following list will need to be upgraded to continue to use the remote tc Runtime and Template downloading capabilities after the March 31, 2023 shutdown date.

tc Server 4.1.0.RELEASE to 4.1.14.RELEASE
tc Server 4.0.0.RELEASE to 4.0.26.RELEASE
All tc Server versions prior to 4.0.0.RELEASE (out of General Support)

These versions of tc Server do not know about the deprecation nor can they be modified to use the new Tanzu Network Repository. After the March 31, 2023 shutdown date these versions of tc Server will be unable to successfully execute get-runtime, list-runtimes, list-templates, and get-template.

tc Server 4.1.x

As of tc Server 4.1.19.RELEASE, the default repository is Tanzu Network which must be configured by setting the token.

As of tc Server 4.1.15.RELEASE, a message will display when tc Server Repository actions are performed informing users that this repository is deprecated.

The default behavior of the tcserver command will change in a release of tc Server scheduled for July 2022. At this time the specific version has yet to be determined. Once the default behavior is changed, a manual configuration step will be required to use the repository features.

tc Server 4.0.x

The default behavior of the tcserver command will not change for this version of tc Server. The option to configure this version of tc Server to use Tanzu Network or a customer hosted repository is available. Starting in tc Server 4.0.27.RELEASE an informational message will be displayed warning of the deprecation.

Note: This version of tc Server will reach End of General Support before the March 31, 2023 shutdown date. Customers should upgrade to the latest version before that date.

tc Server 3.2.x (and earlier)

This release is only supported for customers with extended support. After the March 31, 2023 shutdown date this version of tc Server will not be able to download from the tc Server Repositories and no alternative is being provided other than direct download from Tanzu Network.

What information is sent to the Tanzu Network servers?

The tcserver command makes HTTPS requests to the Tanzu Network using the configured API Refresh Token and sends a User-Agent string identifying itself as tc Server along with the version and OS the tcserver command is running. As part of a standard HTTPS request the public IP Address is available to Tanzu Network.

Please refer to the VMware Privacy Policy for more information on VMware's Privacy Policy.

Customize the User-Agent transmitted to Tanzu Network

For customers wishing not to provide tc Server version and OS information to Tanzu Network, the User-Agent transmitted by tcserver may be customized by setting the following property in conf/tcserver.properties

tcserver.httpclient.useragent=generic agent

Note: This property can not be blank. If an empty value is set the default will be used.

Why do I need to configure my Tanzu Network Refresh Token?

This is a requirement of Tanzu Network to ensure that the EULA has been accepted by the user.

What if I don't want to use Tanzu Network as a Repository?

If you do not configure Tanzu Network or a self-hosted Repository, the commands using these features will fail. However, tcserver will still function for all other commands.

What is the Tanzu Network Refresh Token and how do I find it?

This token is a token provided to users of Tanzu Network.

There can only be one token per Tanzu Network user. Once generated it is only provided to the user once and can not be obtained again. If the token has already been generated, choosing REQUEST NEW REFRESH TOKEN will invalid the previous token.

It may be obtained by logging into Tanzu Network, clicking on the username in the top right, clicking on Edit Profile, and then clicking on the button next to UAA API TOKEN.

How do I configure the Tanzu Network Repository?

For versions of tc Server which have not been updated to know about the new repositories an upgrade to a newer version of tc Server is required.

For versions of tc Server using the deprecated repository as the default, the following configuration properties must be changed to false

tcserver.repository.runtime.deprecated=false
tcserver.repository.template.deprecated=false

The following properties must also be set to true:

runtimes.tanzunet=true
templates.tanzunet=true

In addition the Tanzu Network Refresh Token must be defined. (see below)

For versions of tc Server using Tanzu Network as the default only the Tanzu Network Refresh Token must be defined or a self-hosted repository defined.

This can be defined by using one of the following methods:

tcserver.properties

The following key property should be in conf/tcserver.properties

tanzunet.token=<REFRESH_TOKEN>

This takes precedence over the environment variable.

More information may be found at tc Server Repositories

Environment Variable

The TCS_TANZUNET_TOKEN environment variable may be defined to avoid setting the value in a text file.

TCS_TANZUNET_TOKEN=<REFRESH_TOKEN>

Command Line (4.1.x only)

In tc Server version 4.1.x a command line option is available to allow tcserver.properties to be set/overwritten.

--tcs-property tanzunet.token=<REFRESH_TOKEN>

Securing the Tanzu Network Refresh Token

At this time the token must be provided in plain text, however, the token can be provided via an environment variable which gives flexibility on how it is defined and where it is stored.

I see different templates listed from the Tanzu Network Repository than the deprecated repository. Why is this?

The deprecated repository divided templates by the tc Server edition. This isn't possible with the Tanzu Network repository. Therefore a template will be listed for all editions when listing templates available from the Tanzu Network repository.

How do I configure a self-hosted repository?

Note: Please use caution with hosting tc Server artifacts such as tc Runtimes as per the VMware End User License Agreement redistribution of tc Server artifacts is restricted. Self-hosted repositories should not be publicly available for anonymous downloads over the Internet.

Hosting with a tc Runtime Instance

A new template has been introduced to tc Server which when applied to an instance will configure the instance for hosting tc Runtime and templates. This template is named tcserver-repository.

Create a new instance and apply the tcserver-repository template such as follows:

tcserver create corp-tcserver-repository -t tcserver-repository

Note: This template accepts tcserver-repository.docBase and tcserver-repository.path as properties. The default value of tcserver-repository.docBase is ./../../repository/ and default value of tcserver-repository.path is empty which gives it a context path of /. If the docBase does not exist it is not created and the instance will not start.

Note: This template uses the same defaults as any other tc Runtime Instance for restricting access. Additional configuration may be necessary.

Configuring `tcserver` to use the repository

The conf/tcserver.properties needs a value configured for the key runtimes.repository.url. This value is used as the root of the tc Runtime repository.

runtimes.repository.url=http://tcserver-repo.internal.example.com:8080/runtimes

This value is used by tcserver to find the runtimes.json file. As an example in the above key/value pair tcserver will make a HTTP GET for http://tcserver-repo.internal.example.com:8080/runtimes/runtimes.json and the paths specified in that file should be relative to http://tcserver-repo.internal.example.com:8080/runtimes.

The tc Runtimes Repository Layout

At the root of the repository is a file called runtimes.json. This file is accessed by the tcserver command to determine what artifacts are available and how to find them.

The runtimes.json file structure:

{
  "runtimes": [
    {
      "version": "<tc Runtime Version>",
      "path": "<relative path to .zip archive>",
      "compatableWith": "<tc Server major.minor version this archive is compatible>"
    }
  ]
}

Note: Duplicate versions are ignored only the first entry matching a version number is processed by tc Server.

Example runtimes.json file:

{
  "runtimes": [
    {
      "version": "8.5.76.A",
      "path": "pivotal-tc-runtime-8.5.76.A.RELEASE.zip",
      "compatableWith": "4.0"
    },
    {
      "version": "7.0.109.C",
      "path": "pivotal-tc-runtime-7.0.109.C.RELEASE.zip",
      "compatableWith": "4.0"
    },
    {
      "version": "9.0.59.A",
      "path": "pivotal-tc-runtime-9.0.59.A.RELEASE.zip",
      "compatableWith": "4.0"
    },
    {
      "version": "9.0.58.A",
      "path": "pivotal-tc-runtime-9.0.58.A.RELEASE.zip",
      "compatableWith": "4.0"
    }
  ]
}

The relative path is to the runtimes.json location.

The tcserver command can assist in maintaining this file. The get-runtime command has a new option to download to a repository and update the runtimes.json file. When the --repository-directory option is specified the directory is used to download the .zip archive to and the runtimes.json file is created or updated. When this option is used the runtime is not installed into the local runtimes directory.

tcserver get-runtime 9 --repository-directory /opt/pivotal/tcserver/instances/corp-tcserver-repository/runtimes

Will there be any other breaking changes in the future?

We understand that such a change in maintenance releases is inconvenient and strive to avoid making any breaking changes. We hope that allowing approximately 1 year to adjust to the change is sufficient.

It is difficult to predict the future, however, at this time we do not intend to introduce any other breaking changes during the tc Server 4.1.x long term support release.

Future versions such as 4.2.0 or 5.0.0 may included breaking changes.