getporter / vscode-extension

Visual Studio Code tools and integration for Porter

Visual Studio Code Porter Tools

This extension helps you to edit Porter resource files and view information about installed bundles. Features include:

• Create a Porter project
• Create and organize bundle installation steps
• Build your Porter project into a bundle
• Install a Porter bundle
• Code completion and error checking for the Porter manifest
• Navigation around the Porter manifest (Go To Definition and Find References)

For more about Porter see https://getporter.org/.

Prerequisites

You will need the Porter binary on your system PATH. If you don't have this, you can download it from https://getporter.org/install/.

If you have the Porter binary but it's not on your path, you can specify the file path using the vscode-porter > porter-path configuration setting. This must include the full file path, not just the directory (and must include the .exe extension on Windows).

Telemetry

This extension collects telemetry data to help us build a better experience for building bundles with Porter and VS Code. We only collect the following data:

• Which commands are executed
• Whether a command succeeded or failed

We do not collect any information about image names, paths, error messages, etc. The extension respects the telemetry.enableTelemetry setting which you can learn more about in our FAQ.

Contributing

This project welcomes contributions and suggestions. See our Contributing Guide to learn how to build and test the Porter VS Code extension.

This project adheres to Porter's Code of Conduct.

vscode-extension's Issues

Intellisense for consuming step outputs

When a prior step has an output, that output should be available as an completion item for values in subsequent steps (bundle.output.<stepname>.<outputname> I think).

Capturing stdout from porter hangs around 1k lines

When porter schema returns more than 1,000 lines (estimated), the extension never is able to return from collecting the schema. If I hard code the schema into the extension it works fine, however.

JSON Schema issue with custom actions and images

using https://github.com/jeremyrickard/do-porter:

porter v0.20.0-beta.1 (bd40408)

VS Code porter extension: 0.0.1

Find References finds 'references' in comments

Snippets and fragments for porter.yaml

We should identify some common fragments for porter.yaml and surface those either as snippets or via special-purpose commands, e.g. adding a new mixin step with auto adding the mixin name to the mixins section if not yet there.

Support bundle.images.*

The porter.yaml file can have image maps defined and the templating supports referencing those images by name. It is currently a dictionary map (which none of the other types do, they are all lists with a name field).

Is it a huge pain to add support for this type as it works right now?

images:
  mysql:
      description: MySQL
      imageType: docker
      repository: docker.io/mysql
      tag: "5.7.28"

install:
- helm:
    description: "Install MySQL"
    name: "{{ bundle.parameters.mysql-name }}"
    set:
      image: "{{ bundle.images.mysql.repository }}"
      imageTag: "{{ bundle.images.mysql.tag }}"

Extension doesn't autocomplete some sections anymore?

I used to be able to type the name of a mixin in the install section and autocomplete it. The extension would then add placeholders for all required fields.

e.g. I would type

install:
  - exec[TAB]

and get something like this

install:
  - exec:
       description:
       command:

and when I began to add a new field under exec, it would give me a list of values from the schema.

Instead this is what is happening (recording below). It doesn't show me the list of mixin names when I autocomplete under the install section, and when I try to tab complete the required fields for the mixin, it doesn't work. Also the autocomplete provided for the mixin fields is coming from values seen in the file previously and not from the schema.

Any ideas on what is messed up? I tried reinstalling the porter+yaml extensions and that didn't help. I could try reinstaling vs code entirely (which I've had to do before when things got weird) but since autocomplete is working for other parts of the file such as parameters, I'm wondering if there's been a change in the extensions or vs code that would cause this?

Screen.Recording.2021-10-01.at.3.03.35.PM.mov

Support Workspace Trust

Hello 👋 I'm from the VS Code team.

Recently, we have been exploring a security feature we refer to as Workspace Trust. This feature is intended to centralize and unify a security conscious decision required by a variety of VS Code features. With workspace trust, the user will be able to declare whether or not they trust the folder that is opened in VS Code before these features are executed.

Why you should care

Your extension is incredibly popular with VS Code users! We want to make sure that those users have a delightful experience with workspace trust and that includes extension authors deciding how much of their extension is supported in an untrusted workspace.

Workspace Trust experience

You can enable the feature with the following setting security.workspace.trust.enabled. Once enabled, you will see the following dialog when opening folders in VS Code.

This dialog is important for allowing the user to make a decision early and understand the impact of their decision. Once you understand the feature, you may want to customize when to display the dialog using the setting security.workspace.trust.startupPrompt.

You can follow the development of Workspace Trust and provide feedback in issue #106488.

Workspace trust API

First off, all of what I am about to say can be found in issue #120251. That issue will include discussion of the feature and any updates to the feature.

The Workspace Trust extension API is now in stable. This allowed us to release the first cut of our guide for onboarding your extension to Workspace Trust. The API is small, so here is a quick look.

You can declare your extension to provide complete, partial or no support in untrusted workspaces using the untrustedWorkspaces capability in package.json.

The following example declares that the extension is supported completely in untrusted workspaces. In this case, the extension is enabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": true
  }
}

The next example declares that the extension is not supported in untrusted workspaces. In this case, the extension is disabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": false
  }
}

The third option is to declared limited support. There are three tools provided to you when you select the limited option.

First, if you have a setting that can be configured in the workspace but requires the workspace to be trusted in order to apply the workspace value, then you can include the setting using restrictedConfigurations array property in untrustedWorkspaces object. Doing so, VS Code will ignore the workspace value of these restricted settings when your extension reads these settings values using the VS Code Workspace Configuration API.

The following example declares the settings that are restricted in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": "limited",
    "restrictedConfigurations": [
      "markdown.styles"
    ]
  }
}

Next, you can also check and listen if the current workspace is trusted or not programmatically using the following API:

export namespace workspace {
  /**
    * When true, the user has explicitly trusted the contents of the workspace.
    */
  export const isTrusted: boolean;
  /**
    * Event that fires when the current workspace has been trusted.
    */
  export const onDidGrantWorkspaceTrust: Event<void>;
}

Lastly, you can hide commands or views declaratively with the isWorkspaceTrusted context key in your when clauses.

A far more detailed guide on how to onboard which will be updated as we receive feedback can be found in issue #120251.

Rollout plan

Workspace Trust will remain disabled for the month of May, but we are planning on enabling this by default in the future. To prepare for that day, we would love for you to try it out and provide feedback.

We'd love your feedback

Since this issue was created in an automated fashion, we won't be monitoring the responses in this issue (our notifications would explode!). Instead we ask you to drop questions, and feedback in issue #120251 as we've mentioned above.

We're excited to see what you do with workspace trust!

Move step up/down

A command to reorder steps within an action. Longer term could be a GUI, but a relatively simple first step could be to move the step where the cursor is up or down within its action.

Scope out a Porter-coat extension

I don't think we can continue to build and extend duffle-coat. it works great. But once duffle is 1.0, and duffle coat works as it does, I think we need a porter-coat -- or at least we need to understand how to do porter coat, what the ramifications are for size, perf, and engineering resources.

Visual manifest assembler

For simple cases it would be great to be able to compose chunks of manifest visually rather than having to tangle with the YAML. (Though VS Code may not be the right environment for this, what with, you know, the whole TEXT-BASED TEXT EDITOR SPECIALISED IN TEXTUALLY EDITING TEXT thing.)

Porterise existing deployment code

We have identified a key workflow as "I already have { a Terraform script for AKS / a Helm chart for nginx ingress / a k8s manifest for Consul }, I just want to shove it into my bundle" -> "it produces this output, I want to grab that and pass it to the next step". That is, we do not start from "I want to write a porter.yaml" but from "I have some deployment code, I want to Porterise it."

This implies we should be able to point to existing deployment code and say "add this to my porter.yaml" and to point to outputs (somehow identified) in said code and say "make this visible to Porter."

cc @carolynvs to help make the vision more concrete

Wiggles for references to undeclared variables

Like if you write {{ bundle.credentials.kubconfig }} instead of kubeconfig then it should be all in your face going WIGGLE WIGGLE.

Support porter namespaces

Porter supports namespaces (https://porter.sh/cli/porter_list/#options), but there is no option to use non-global namespace in vscode extension!

extension takes over intellisense for all YAML files, not just porter.yaml

1. Create a directory with a porter.yaml and a kubernetes manifest.
2. Open the directory in VS Code with the Porter extension enabled.
3. Open the kubernetes manifest first. Note that there are no red squiggles. Now close it.
4. Open the porter.yaml. Now close it.
5. Re-open the kubernetes manifest and note that it is being validated against the Porter extension, red squiggles galore because it is in fact not a porter.yaml.

porter.yaml

name: HELLO
version: 0.1.0
description: "An example Porter configuration"
tag: getporter/porter-hello

mixins:
  - exec

install:
  - exec:
      description: "Install Hello World"
      command: ./helpers.sh
      arguments:
        - install

upgrade:
  - exec:
      description: "World 2.0"
      command: ./helpers.sh
      arguments:
        - upgrade

uninstall:
  - exec:
      description: "Uninstall Hello World"
      command: ./helpers.sh
      arguments:
        - uninstall

manifests.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: demospace

Support intellisense for new file types

In Porter v1, we introduced some new files that people will be editing by hand and it would be great if VS Code would autocomplete these documents when the Porter extension is installed.

• credential set
• parameter set
• installation
• plugins (the file argument passed to porter plugins install -f plugins.yaml)

Here is an example of what they look like and they are documented at https://getporter.org/reference/file-formats/ with links to the corresponding json schema files.

Credential Set

schemaType: CredentialSet
schemaVersion: 1.0.0
namespace: demo
name: whalegap
credentials:
  - name: kubeconfig
    source:
      path: /Users/carolynvs/.kube/config

Parameter Set

schemaType: ParameterSet
schemaVersion: 1.0.0
namespace: demo
name: hello-llama
parameters:
  - name: name
    source:
      env: USER

Installation

schemaType: Installation
schemaVersion: 1.0.0
name: demo
namespace: demo
bundleRepository: carolynvs/tabbycat-demo
bundleVersion: 0.2.1

Plugins

schemaType: Plugins
schemaVersion: 1.0.0
plugins:
  helm3:
    version: v1.0.1
    url: https://github.com/MChorfa/porter-helm3/releases/download

Seems like before porter releases we should tweak the schemaVersion field to indicate which file it is, e.g. schemaVersion: "credential-set-1.0.0", so that VS code can detect the type of file? Or do you recommend another way, like a separate field like kind: credential-set`? Porter now adds a schemaType field so that we can detect the file type. So if a file is yaml, and it contains a known schemaType, then we should apply the corresponding json schema so that the user gets autocomplete.

Since the schema for these is fixed (unlike porter.yaml which is generated directly by porter on demand), I was thinking that the extension could download the schema from a well-known url, e.g. https://getporter.org/schema/VERSION/FILE_TYPE.json. So the installation schema from https://raw.githubusercontent.com/getporter/porter/release/v1/pkg/schema/installation.schema.json (this isn't the URL we want to use in the extension) would be available at https://getporter.org/schema/v1/installation.schema.json (this is the URL to use in the extension, so that we can improve or fix it later as needed using URL redirects).

Identify unmatched upgrade/uninstall steps

We could create a command that looks at all the install steps and goes "is there a matching step in upgrade and uninstall" e.g. a Helm step that creates a Helm release but isn't paired with another Helm step to remove that release. Not sure if this is feasible or makes sense, but might address a likely source of mistakes if we can make it viable.

Create bundle parameter or credential from selected value

The user should be able to select a block of text in the active document (e.g. exec command, ARM template, etc.) and choose a 'turn this into a parameter' command. This should create a suitable parameter in the porter.yaml. Ideally, it should also modify the source location to reference the parameter, but that may be tricky without knowing the source location syntax and how the parameter is passed into the invocation image - but it will at least be possible if the source is the porter.yaml file itself.

It should also be possible to turn the value into a credential instead of a parameter.

MacOS: Create Project is a no-op

most recent of both macos and this extension:ms-kubernetes-tools.porter-vscode-0.0.1

Find references

Get Find References working for parameters, credentials and outputs, so people can readily see where a value gets used.

Or maybe this doesn't add much value over Ctrl+F given how small and simple Porter manifests are.

Visual representation of artefacts

Porter has many of the same artefacts as Duffle - claims, credentialsets, etc. These are represented in the same way as Duffle but are different sets of artefacts, stored in different places. We should represent these visually in the Porter extension, in the same way as we do in the Duffle extension.

Go to definition

Ctrl+Click on a parameter, credential or output reference ({{ bundle.... }}) to go to where it is defined.

I can imagine this being particularly useful for outputs if the manifest gets complicated...