Description

Each component on the components page should link to a detailed page with more information, mainly how to configure it and documentation for all of the fields.

One open question is how we'll know which config object each service uses. We could scrape it based on the imports, but it will be fairly brittle. We may want some way in the clutchdoc or otherwise for a service to declare its config type.

We have some proto documentation capabilities in the docs generator that can list out the object. We'll need to add onto this a bit to scrape comments, etc if we really want to make this effective.

Complexity [S/M/L]: M

Description

Adding some form of asynchronous tasks will allow us to perform jobs that have multiple phases. This can be used to ensure a task was completed by an infrastructure provider. It can also be used to monitor the progress of requests without having to consult multiple tools.

Infrastructure does not normally change immediately upon request: launching a new EC2 instance takes several minutes, same for resizing an ASG, etc. Right now we fire and forget, and it's not possible to monitor completion in Clutch. Future workloads which are async include chunked or gradual changes to infrastructure.

The front-end confirmation page would change to poll the result of a task completing for most workflows. Chat notifications for the result of a task or phase would also allow the operator to set it and forget it for many workflows without having to sit and refresh a screen. Operators may assume that a task will complete successfully so its especially important for us to monitor it for them and notify if it fails.

There are a number of options for managing tasks, we could implement ourselves, use something like AWS Simple Workflow Service, or an open source tool such as Cadence.

Complexity [S/M/L]: L

Description

Error handling is kind of a free-for-all at the moment. For the backend, I think we want to use google.golang.org/grpc/status pretty much all the way down to the service level so that when errors bubble up they aren't generic 500s and can have structure with the details field.

On the frontend, #26 (pbjs services for rpc calls) will help error handling but we should have standard components for rendering full and partial errors.

Most of all, we'll need documentation advising people how to manage errors properly so the user does not encounter confusing or non-existent error states on the frontend.

This can probably be broken down into additional tickets once we scope the initial set of work.

Complexity [S/M/L]: M

Description

Trending cards on the landing page are missing group information.

For example, the 'Terminate Instance' card denotes it's EC2, but does not indicate it's a part of AWS. This ideally would be displayed as a unique icon in the bottom right corner of the card.

Complexity [S/M/L]: S

Wireframes, Mockups, or Screenshots (if applicable)

Description

We had intended to remove the replace directive after open source since the code would now be publicly downloadable:

However, this breaks all of the frontend build scripts (well anything in tools/ really) because go modules only downloads the backend folder and not the rest of the repository. We will need to figure out a different way of vendoring code outside of backend/ tooling. Or move our go.mod to the top of the project.

Expected Behavior
A scaffolded version of Clutch builds successfully without the code being checked out in the GOPATH.

Actual Behavior

bash: /home/dhochman/go/pkg/mod/github.com/lyft/clutch/[email protected]/../tools/install-yarn.sh: No such file or directory

~/go/pkg/mod/github.com/lyft/clutch/[email protected] $ ls
api  clutch-config.yaml  cmd  gateway  go.mod  go.sum  id  LICENSE  main.go  middleware  mock  module  resolver  service  tools.go

(no frontend code available from module)

Version

124f381

Other Context
N/A

Description

Add Storybook to Clutch to provide a design system for components and workflows.

Complexity [S/M/L]: M

Description

Pop an additional confirmation modal or interstitial for risky actions.

In the future, this may be server-controlled with risk scoring to determine whether or not to pop the modal.

Complexity [S/M/L]: S

Wireframes, Mockups, or Screenshots (if applicable)

Description

Add CI to review licensing of Go dependencies. This should be similar to the existing node dependency CI

Complexity [S/M/L]: S

Description

Add a CI job to check for broken links in the documentation.

Could look into using something like broken-link-checker or linkinator from the generated preview site.

Complexity [S/M/L]: S

Description

https://github.com/uber-go/tally already has a built-in prometheus reporter, just need to add a config hook to https://github.com/lyft/clutch/blob/master/api/config/gateway/v1/gateway.proto and wire it up in the gateway initialization code with some changes to the mux/handler.

Complexity [S/M/L]: S

Wireframes, Mockups, or Screenshots (if applicable)

Description

Give a quick overview of Clutch's core features in a video via a couple of sample workflows. Also show auditing capabilities, resolver, creating a new workflow, etc.

Complexity [S/M/L]: S

Description

There shouldn't be any scenario where the frontend needs to access the config definitions in api/config, yet they are compiled in anyways. This is unnecessary bloat added to frontend/api/index.{js,d.ts}. We should measure the bundle size and what the impact is of removing config objects to understand what kind of other optimizations we could make. One example might be a front-end ignore config or annotation on objects that we know will never be used on the front-end.

Complexity [S/M/L]: S

Wireframes, Mockups, or Screenshots (if applicable)

Description

Clutch is currently using a fork of protobufjs to generate the frontend api modules.

Ideally, Clutch would be using the upstream. Investigate what is required for this, upstream needed fixes, and move Clutch onto https://github.com/protobufjs/protobuf.js.

Complexity [S/M/L]: M

Description

Implement PagerDuty integration within Clutch as a service component.

This will involve both backend and frontend work. An example use of the integration could be adding on-call information within workflows if relevant.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
TODO

Description

Add resources configuration diffing to the Remote Triage workflow.

Complexity [S/M/L]: S

Wireframes, Mockups, or Screenshots (if applicable)
TODO

Description

After 3-6 months of initial open-source availability, we will want to offer versioned builds. Guessing we will use semver but we'll need details on what constitutes major/minor version upgrades, how to do a release, and automated tooling (hopefully). Will also need a security release process.

For an example, see https://github.com/envoyproxy/envoy/blob/master/RELEASES.md.

Complexity [S/M/L]: L

Description

Currently we don't render histograms or timers into the stats output of the Envoy remote admin endpoint. Either we'll need to flatten these into normal key/value pairs (not preferable) or add richer support for displaying values in the remote triage UI.

Complexity [S/M/L]: M

Description

There need to be two gRPC listeners. One for grpc-gateway to proxy JSON requests to, always running in insecure mode and only bound to localhost, and a second that is publicly exposed which can offer SSL termination.

Currently Clutch can not be run in secure mode due to this shortcoming. The config already exists in the proto it just requires implementation.

Complexity [S/M/L]: M

Description

Add an endpoint to the backend that serves feature flags. Initially this can be a true/false per variable. Later we will want to add per-user and per-group targeting for features, so that a feature developer can pilot the feature in a real environment without exposing it to all users.

On the frontend, we'll need a library that can easily flip workflow packages on and off based on the values. The values will need to block loading.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
N/A

Description

We have a topology API definition from the original private implementation of Clutch.

https://github.com/lyft/clutch/blob/master/api/topology/v1/topology_api.proto

It is not implemented in the public repo. This API will be used in the future for auto-complete, fast resource lookup (compared to vendor API), and relationship discovery (e.g. which service or user owns a resource such as a DB).

Complexity [S/M/L]: L

Milestones

• Database schema and configuration
• Topology cache scaffolding
• Topology cache protos
• Topology cache leader election
• Topology cache cashing functionality
• Topology cache actually populating cache (k8s)
• Topology cache actually populating cache (aws)
• Cache expiry
• Topology Search API Protos
• Topology Search API

Will add more milestones as we make progress.

Wireframes, Mockups, or Screenshots (if applicable)

Description

Add an endpoint to the backend that has the ability to update kubernetes deployment objects.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)

Description

Allow systems to call into Clutch rather than only users.

Would be nice to manage tokens and applications via an Admin UI, see #29 (stateful sessions) for more work in this area.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)

Description

The select dropdown menu covers the input field when opened.

Expected Behavior

The input field should always be visible, even when the selector is open.

Actual Behavior

Version
master

Description

The workflow package docs are generated from scraping each workflows index file via pattern matching. This is a bit brittle since this structure could change.

Complexity [S/M/L]: S

Description

The oauth2 flow is already implemented, will just need some tweaks to support GitHub as the current authn implementation is only set-up for OIDC flows (e.g. Okta).

InfluxDB's Chronograf backend has a great example of handling GitHub and other forms of login generically that should be adaptable to Clutch's components. https://github.com/influxdata/influxdb/blob/master/chronograf/oauth2/github.go

Complexity [S/M/L]: M

Description

As part of the oauth2 flow, we should store the original URI that the user was accessing.

The GetStateNonce function on the Provider interface will add a state param struct so it can encode this into the nonce.

Complexity [S/M/L]: S

Description
Currently we only use pbjs to serialize request objects. Services will make accessing APIs on the backend prescriptive, reducing the burden on the developer to handle API calls and errors.

https://github.com/protobufjs/protobuf.js#using-services

Here's an example of accessing grpc-gateway endpoints with protobuf.js: grpc/grpc-web#80 (comment).

Complexity [S/M/L]: M

Description

Provide a wireframe template that contributors can easily build off of for features.

Investigation is required into which tooling to use for the wireframe.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
TODO

Description

Clutch currently uses stateless sessions for authn (JWT is signed and valid until expiry). This makes session invalidation impractical, so it is not implemented. In Lyft's network topology, this is not a security issue. To accommodate all environments, sessions should be stateful. This will also allow us to do delegated authn with other systems (e.g. GitHub, K8s), storing additional tokens for the user in the database.

The design for stateful sessions storage should also allow for storing user preferences on the same database record.

Complexity [S/M/L]: M

Description
When you build a fresh custom gateway using make scaffold-gateway all workflows are missing.
Expected Behavior
The default workflows, as well as the echo workflow, should appear in clutch.
Actual Behavior
There are no workflows

Version
124f381

Other Context
I think this is because the workflows in

Description

Add a dependency management bot for frontend and backend packages.

One option could be to use Dependabot as it is owned by GitHub and might have better support/easier integration. Another popular tool is Renovate.

Complexity [S/M/L]: S

Description

Integrate a data visualization library into Clutch.

One possibility is using nivo as they have a robust component library. Another option if we are looking for something more custom is building component on top of VX.

Complexity [S/M/L]: L

Wireframes, Mockups, or Screenshots (if applicable)
TODO

Description
https://github.com/lyft/clutch/runs/917248556
Expected Behavior
Tests pass.
Actual Behavior

  1 failing

  1) Navigation drawer
       hides routes:
     AssertionError: Timed out retrying: expected '[ <a.sc-fzqNJr.jCCdPB.MuiListItem-root.MuiListItem-dense.MuiListItem-gutters>, 1 more... ]' not to be 'visible'
      at Context.eval (http://localhost:3000/__cypress/tests?p=cypress/integration/navigation_spec.js:32:58)

Version
Happening on various versions of main.

Description

Similar to #8 (adding a Slack gateway to Clutch), allow certain capabilities to be accessed through a command-line interface that remotely communicates with the Clutch APIs.

This is leveraging the infrastructure control plane concept. We already have systems integrated behind Clutch with auditing, authorization, etc. No need to reimplement that for a command-line tool.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
$ clutchctl aws describe asg myAsg123

Description

The gateway should cancel contexts and wait for them to complete before shutting down on SIGTERM, etc.

We have code in our private impl that we can provide for reference.

In the future, we will also want to send some kind of cleanup signal to services to allow them to gracefully shutdown. Probably filed as a separate issue once we fix this one, as it way require changes to the service constructor.

Complexity [S/M/L]: S

Description

Currently the feedback button opens an external URL, premised that it is a page where users can input this data.

The feedback button should instead present a modal, customizable via configuration, with input fields that get posted to a user-specified URL.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)

Description

The build failed very fast....

Following document: https://clutch.sh/docs/getting-started/local-build

and run make

Expected Behavior

Build Succeeds.

Actual Behavior

info: Downloading protoc-v3.11.4 to build environment
info: Downloading protobufjs to build environment
Unrecognized option: --cwd
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.
Makefile:20: recipe for target 'api' failed
make: *** [api] Error 1

Version
git master repo

Description
On https://clutch.sh/docs/about/what-is-clutch/ when clicking roadmap it goes to https://clutch.sh/docs/roadmap which 404s instead of https://clutch.sh/docs/about/roadmap

Expected Behavior
Get a page with the roadmap

Description

Audit that Clutch-specific annotations in https://github.com/lyft/clutch-preview/blob/master/api/api/v1/annotations.proto are always present on endpoint definitions.

Complexity [S/M/L]: M

Description

Implement server-side rendering of the frontend assets.

One possible solution is having a separate frontend service with a node backend. Another is looking into using goja for this.

Complexity [S/M/L]: L

Description

Instead of relying on code review to catch breaking changes, we can do so with tooling.

https://github.com/nilslice/protolock
https://buf.build/docs/migration-protolock/

At the time of this writing, Clutch's APIs have limited stability guarantees so we have to figure out how to balance that with the linting. Either way, we should avoid breaking changes whenever possible.

Complexity [S/M/L]: S

Description

Certain tasks should require explicit approval from an additional party, i.e. +1 from another operator for the task to proceed.

Possible implementations:

• Allow the user to select another user from a list
• Send a chat message to the user asking for their approval, directing them to an approval page
• Generate a link for the user to share

Complexity [S/M/L]: L

Wireframes, Mockups, or Screenshots (if applicable)
TODO

Description

Allow READ actions to be accessed through a Slackbot interface.

Initially this could be a generic JSON dump of the endpoint data. Later we can have rich transforms that render the data in a more friendly format.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
@clutchbot aws asg describe myAsg123
@clutchbot k8s pod describe <cluster> <mypod>

Description

Set up a CI job to run the scaffolding script and, on changes, push the updated output to an example reference repository.

Complexity [S/M/L]: S

Description

The component registry is currently just a map.

1. The registry should never be modified after startup, the Gateway should lock it after instantiation of the configured components.
2. Helper methods should make adding and getting references to components easier.
3. There should be a way of aliasing components, both in the consumer component and actual component.

Complexity [S/M/L]: M

Description

In order to populate the description on the components page of the docs, we use a custom clutchdoc stanza.

We should lint all components to ensure they have a properly filled in clutchdoc.

Not sure if this belongs as part of golangci-lint or a separate tool. We may want to similarly audit front-end packages for documentation hooks.

Complexity [S/M/L]: S

Description

Add an audit log viewer to the frontend, on top of the audit API defined in https://github.com/lyft/clutch/blob/master/api/audit/v1/audit.proto.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
TODO

Description

Our repeatable build tooling is mostly bash scripts at the moment, managing protoc, yarn etc. Bazel would be ideal for this kind of project, i.e. a multi-language monorepo.

IIRC, managing generated code with Bazel and making it available for code completion in the IDE has some weirdness to it. Some investigation needed there.

Complexity [S/M/L]: L

Description

The documentation currently only support hot reloading for frontend changes. Add hot reloading to pick up changes to the markdown files that are generated and consumed by the frontend.

Complexity [S/M/L]: S

Description

Add functionality to generate short links for Clutch workflows that support state rehydration.

Complexity [S/M/L]: M

Wireframes, Mockups, or Screenshots (if applicable)
TODO