rancher
/
dashboard
mirror of https://github.com/rancher/dashboard.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add info from knowledge transfers to developer docs

This commit is contained in:
Catherine Luse 2022-02-11 01:12:00 -07:00
parent b1adb12383
commit 1a32b37cbe
7 changed files with 207 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
docs/developer/api-resources-and-schemas.md
View File

@ -82,6 +82,14 @@ this.$store.getters['cluster/schemaFor'](POD)`
As mentioned before a schema dictates the functionality available to that type and what is shown for the type in the UI.
## Types
Each type has a Kubernetes API group and a name, but not necessarily a human-readable name. Types are used mainly for building side navigation and defining how the UI should build forms and list views for each resource. For more information about types and how to use them, there are helpful comments in `store/type-map.js`.
### Cluster Management Types
Resources for cluster management are stored in the `local` cluster (the one that runs the Rancher server). The `management.cattle.io` API group indicates the resources that are backing the old Norman API.
# Vuex Stores
There are 3 main stores for communicating with different parts of the Rancher API:
@ -125,7 +133,7 @@ Store objects are accessed in different ways, below are common ways they are ref
> Bad - Does not trim text, issues when resource type contains "`.`" - ``store.getters['i18n/t'](`typeLabel.${ NORMAN.SPOOFED.GROUP_PRINCIPAL }`, { count: 2 })``
## Checking User Permissions
## Checking User Permissions with Schemas
The schema can be checked in the Rancher API at:
@ -139,7 +147,7 @@ const hasAccess = this.$store.getters[`cluster/schemaFor`](type);
return hasAccess ? this.$store.dispatch('cluster/findAll', { type }) : Promise.resolve([]);
```
## Model Architecture
## Models
The ES6 class models in the `models` directory are used to represent Kubernetes resources. The class applies properties and methods to the resource, which defines how the resource can function in the UI and what other components can do with it. Different APIs return models in different structures, but the implementation of the models allows some common functionality to be available for any of them, such as `someModel.name`, `someModel.description`, `setLabels` or `setAnnotations`.
@ -147,7 +155,7 @@ Much of the reused functionality for each model is taken from the Steve plugin.
The `Resource` class in `plugins/steve/resource-class.js` should not have any fields defined that conflict with any key ever returned by the APIs (e.g. name, description, state, etc used to be a problem). The `SteveModel` (`plugins/steve/steve-class.js`) and `NormanModel` (`plugins/steve/norman-class.js`) know how to handle those keys separately now, so the computed name/description/etc is only in the Steve implementation. It is no longer needed to use names like `_name` to avoid naming conflicts.
## Extending Models
### Extending Models
The `Resource` class in `plugins/steve/resource-class.js` is the base class for everything and should not be directly extended. (There is a proxy-based counterpart of `Resource` which is the default export from `plugins/steve/resource-instance.js` as well.) If a model needs to extend the basic functionality of a resource, it should extend one of these three models:
@ -157,21 +165,33 @@ The `Resource` class in `plugins/steve/resource-class.js` is the base class for
The Norman and Hybrid models extend the basic Resource class. The Hybrid model is extended by the Steve model.
## Dehydration and Rehydration
The Rancher API returns plain objects containing resource data, but we need to convert that data into classes so that we can use methods on them.
Whenever we get an object from the API, we run the `classify` function (at `plugins/steve/classify.js`) which looks at the type field and figures out what type it is supposed to be. That file gives you an instance of a model which you can use to access the properties.
This 'rehydration' process is important for server-side rendering, in which the server side returns a block of JSON that needs to be converted to classes. In `plugins/steve/rehydrate-all.js`, we use `this.nuxt.hook` to add a hook in which nuxt looks over all the objects. It recurses over the object from nuxt, which is the data that you get back from the server when server-side rendering mode is turned on, and converts all of the objects to classes. While the `rehydrate-all` code is not used in production, it may be in the future.
We also 'dehydrate' resources by stripping out properties with double underscores before sending data to the Rancher API. We remove these properties because they are only used on the client side.
## Creating and Fetching Resources
Most of the options to create and fetch resources can be achieved via dispatching actions defined in `/plugins/steve/actions.js`
| Action| Example Command | Description |
|--------|-------|-----|
| Create | `$store.$dispatch('<store type>/create', <new object>)`| Creates a new Proxy object of the required type (`type` property must be included in the new object) |
| Clone | `$store.$dispatch('<store type>/clone', { resource: <existing object> })` | Performs a deep clone and creates a proxy from it |
| Fetch all of a resource type | `$store.dispatch('<store type>/findAll', { type: <resource type> })` | Fetches all resources of the given type. Also, when applicable, will register the type for automatic updates. If the type has already been fetched return the local cached list instead |
| Fetch a resource by ID | `$store.dispatch('<store type>/find', { type: <resource type>, id: <resource id> })` | Finds the resource matching the ID. If the type has already been fetched return the local cached instance. |
| Fetch resources by label | `$store.dispatch('<store type>/findMatching', { type: <resource type>, selector: <label name:value map> })` | Fetches resources that have `metadata.labels` matching that of the name-value properties in the selector |
| Function | Action | Example Command | Description |
|-------------|--------|-----------------|-----|
| `create` | Create | `$store.$dispatch('<store type>/create', <new object>)`| Creates a new Proxy object of the required type (`type` property must be included in the new object) |
| `clone` | Clone | `$store.$dispatch('<store type>/clone', { resource: <existing object> })` | Performs a deep clone and creates a proxy from it |
| `findAll` | Fetch all of a resource type and watch for changes to the returned resources so that the list updates as it changes. | `$store.dispatch('<store type>/findAll', { type: <resource type> })` | Fetches all resources of the given type. Also, when applicable, will register the type for automatic updates. If the type has already been fetched return the local cached list instead |
| `find` | Fetch a resource by ID and watch for changes to that individual resource. | `$store.dispatch('<store type>/find', { type: <resource type>, id: <resource id> })` | Finds the resource matching the ID. If the type has already been fetched return the local cached instance. |
| `findMatching` | Fetch resources by label and watch for changes to the returned resources, a live array that updates as it changes. | `$store.dispatch('<store type>/findMatching', { type: <resource type>, selector: <label name:value map> })` | Fetches resources that have `metadata.labels` matching that of the name-value properties in the selector. Does not support match expressions. |
> Once objects of most types are fetched they will be automatically updated. See [README#synching-state](../../../README.md#synching-state) for more info. For some types this does not happen. For those cases, or when an immediate update is required, adding `force: true` to the `find` style actions will result in a fresh http request.
Once objects of most types are fetched they will be automatically updated. See [README#synching-state](../../../README.md#synching-state) for more info. For some types this does not happen. For those cases, or when an immediate update is required, adding `force: true` to the `find` style actions will result in a fresh http request.
It's possible to retrieve values from the store synchronously via `getters`. For resources this is not normally advised (they may not yet have been fetched), however for items such as schema's is valid. Some of the core getters are defined in `/plugins/steve/getters.js`
## Synchronous Fetching
It's possible to retrieve values from the store synchronously via `getters`. For resources this is not normally advised (they may not yet have been fetched), however for items such as schemas, it is valid. Some of the core getters are defined in `/plugins/steve/getters.js`:
```
$store.getters['<store type>/byId'](<resource type>, <id>])
@ -179,6 +199,33 @@ $store.getters['<store type>/byId'](<resource type>, <id>])
$store.getters['<store type>/schemaFor'](<resource type>)`
```
The `all`, `byId` and `matching` getters are equivalents of the asynchronous `findAll`, `find` and `findMatching`, respectively.
## Watching Resources
For each API call, a websocket is created for the cluster you're talking to. For example:
- If you `findAll` Pods, Rancher will watch all Pods after that.
- if you get an individual resource using `findMatching`, it will watch a particular resource with that ID in a namespace.
If you already called `findAll` for a resource, then do `findMatching`, no additional Pods would be watched because all of the Pod resources are already being watched. The subscribe call uses `equivalentWatch` to detect duplicate watches so that it won't send another request to watch the subset of resources that were already loaded previously.
The `unsubscribe` function is used to unwatch resources. However, as a general rule, resources are never unwatched because Rancher assumes that any data you have already loaded needs to be kept up-to-date.
The code related to watching resources is in `plugins/steve/subscribe.js`.
### Pinging
The UI normally has three websocket connections with `rancher` (Steve's global cluster management), `management` (Norman) and `cluster` (Steve for an individual cluster). The UI is pinged by Steve every five seconds and by Norman every thirty seconds. Steve's messages send the server version they are sent from, which sends another action and reloads the page if the server has been upgraded.
To avoid excessive rerendering, the messages that change state, such as `resource.{create, change, remove}`, are saved in a buffer. Once per second they are all flushed together to update the store.
## Resource Selectors
The `parse` utility function in `utils/selector.js` helps you match or convert labels. For example, `matchLabels` could be used to get all the Pods for each workload.
Kubernetes supports matching with `matchExpressions`, but the UI converts selectors that use match expressions to selectors with `matchLabels` when possible because `matchLabels` is simpler and better supported by Rancher. When loading multiple resources at once from the Rancher API, you can only use `matchLabels`, but if you are loading only one resource at a time, you can use `matchExpressions`.
## Error Handling
When catching exceptions thrown by anything that contacts the API use `utils/error exceptionToErrorsArray` to correctly parse the response into a commonly accepted array of errors
@ -199,6 +246,18 @@ Due to the way Dashboard resources are constructed examining the contents of one
>
> A These are part of the common underlying `resource-instance.js` or, if the resource type has it, the type's own `model`.
## API Calls to Third-party Domains
Rancher includes a proxy that can be used to make requests to third-party domains (like a cloud provider's API) without requiring that the other end supports CORS. Send requests to `/meta/proxy/example.com/path` and the request will be made from the Rancher server and proxied back to you.
## Nodes vs. Machines
Upstream Kubernetes manages nodes, as shown in Cluster Explorer. Rancher deals with machines, which control node provisioning, and they are available from Cluster Management.
When you create a cluster, the cluster has a spec that contains machine pools. Each machine pool uses a machine config (`rke-machine-config`), which configures the size and role of the machine. Rancher sends the configuration to CAPI (Cluster API), which uses it to create the machines.
When provisioning RKE clusters, you could create node templates and define virtual machines in them. Then those definitions could be used when creating node pools. In contrast, RKE2 and K3s cluster provisioning uses CAPI as its standard for provisioning clusters, and CAPI requires that a machine template can only used once per node pool. For that reason, node templates cannot be shared across node pools the same way they used to be able to for RKE provisioning. The forms for provisioning new RKE2 and K3s clusters through Rancher don't introduce the concept of node templates. Instead they let you create new node pools for each new cluster.
## UI Components for Resource Types
The dashboard has a framework and set of components to support (conditional) representation of resource type/s. Common UI features include
@ -210,9 +269,9 @@ The dashboard has a framework and set of components to support (conditional) rep
By default only the table and, if enabled by the resource type, viewing/editing as YAML are enabled. To provide a richer experience the resource's table columns should be defined and custom overview and edit pages provided.
### Resource Lists
The top level list page is defined in `./components/ResourceList`. This displays a common masthead and table for the given resource type. Without any customisation the columns are restricted to a base set of `state`, `nameDisplay`, `namespace` and `ages`.
The top level list page is defined in `./components/ResourceList`. This displays a common masthead and table for the given resource type. Without any customisation the columns are restricted to a base set of `state`, `nameDisplay`, `namespace` and `ages`. More information can be found in function `/store/type-map.js headersFor`.
Any resources returned by `getInstances` should have a `kind` matching the required type. This results in the tables showing the correct actions, handling create/edit, etc.
### Resource Detail Pages

45
docs/developer/auth-sessions-and-tokens.md Normal file
View File

@ -0,0 +1,45 @@
# Auth Sessions and Tokens
# Cookies
Rancher uses the following cookies:
| Name | Description |
|======|=============|
| `R_SESS` | The logged in user's session token |
| `R_PCS` | The user's preferred color scheme, used for server side rendering. If it's auto, it's the user's system preference. |
| `CSRF` | Cross site request. The server sets this cookie. For any request other than a GET request, we have to use Javascript to read this value and use it as a header in the request. That proves we are using our code on Rancher's domain and our header matches that cookie. |
| `R_REDIRECTED` | This cookie is used to redireect users from Ember to Vue when they upgrade from v2.5.x to v2.6.x. |
| `R_LOCALE` | Tracks the user's preferred language. |
When users log in to Rancher, the UI sends the username and password to the back end, then Rancher sends the logged-in user's session cookie in the response back to us. Rancher uses cookies to track the session for the following reasons:
- Cookies are automatically sent by the browser with any request that matches the domain. Note: In some edge cases the browser may not use the port.
- The cookie is http only, which means the browser uses it, but it cannot be accessed by Javascript in the browser. This is an important security feature because it means the cookie cannot be stolen by cross site scripting attacks.
In general, we use the browser's local storage for client-side-only settings including window height and language.
# Third-party Integration with Rancher Auth
Sometimes a third-party application needs to integrate with Rancher such that after you install it as a Helm chart in Rancher, you can also access the application from a link in the Rancher UI.
In the case of Harvester, we injected headers and groups to tell Harvester who the user is and what groups they belong to. This means that Harvester doesn't need to call the Rancher API.
Application integrating with Rancher auth should never maintain their own separate authentication state or session. Due to the difficulty of maintaining consistent authentication state across browser windows and tabs, it would be a security risk to use more than one session along with Rancher's session.
The following should be true of any auth system integrating with Rancher:
- Only Rancher tokens are used to authenticate users.
- The same session token is used for Rancher's session and the third party app session.
- Logging out of Rancher also must also log you out of the third-party application.
- Session storage is not used to store tokens.
We don't recommend using session storage for auth because two tabs will have different storage even if both tabs are opened on the same domain. In that case, opening a new tab on the same domain would show the user a log-in screen. It is a better user experience to be able to share the same session across multiple tabs.
## Custom NavLinks
To set up a link to a third-party navigation link in the left navigation bar, we recommend using the NavLink custom resource. For more information on how to configure custom NavLinks, see the [Rancher documentation.](https://rancher.com/docs/rancher/v2.6/en/admin-settings/branding/#custom-navigation-links) NavLinks open in another window or tab. You can define grouped entries in them as well.
A third-party app installed with a Helm chart can deploy the NavLink custom resource along with the app. When this resource is deployed, the link will be hidden for users without access to the proxy.

22
docs/developer/navigation.md
View File

@ -1,22 +0,0 @@
# Navigation
## Products & Side Nav
Products are top level features that are reached via the header top left menu. Some are built in (`Cluster Explorer`, `Apps & Marketplace`, `Users & Authentication`) and some are enabled after installing the required helm charts via `Apps & Marketplace` (see 'Rancher' charts in the `Charts` page ).
Configuration for each product can be found in `/config/product`. These define the product itself, menu items in side nav, spoofed types, etc. These settings are stored in the `type-map` section of the store and manipulated with functions in `/store/type-map.js`. Some stand out functions include
- `basicType` - Defines a type or group of types that will show in the side nav
- `weightGroup`/`weightType` - Set the position of the group/tye for this product. Pay attention to the `forBasic` boolean which should be true if the menu item is classed as basic.
- `configureType` - Provider/Override UI features for the type (is creatable, show state in header/table, etc). These are accessible via the `type-map/optionsFor` action
> There's some docs for these functions are the top of the `type-map.js` file
## Virtual and Spoofed Resource Types
The side nav is populated by resource types that have been applied to the current product. Virtual Types are a way to add additional menu items. These are purely for adding navigation and do not support tables or details views. Examples of virtual types can be found by searching for `virtualType`. For instance the `Users & Authentication` product has a virtual type of 'config' to show the `Auth Providers` page.
Spoofed Types, like virtual types, add menu items but also define a spoofed schema and a `getInstances` function. The latter provides a list of objects of the spoofed type. This allows the app to then make use of the generic list, detail, edit, etc pages used for standard types.
> Any resources returned by `getInstances` should have a `kind` matching required type. This results in the tables showing the correct actions, handling create/edit, etc.

36
docs/developer/performance.md Normal file
View File

@ -0,0 +1,36 @@
# Performance
## Flame Graph
To inspect performance in the Rancher UI, open the Chrome developer tools and click the **Performance** tab. From there, you can see a flame chart to see what tasks take the most time. You can record performance, analyze local time vs. network time, and analyze whether some network calls can be made serially or in parallel.
The flame charts have more useful function names when the dashboard is running locally because in that case, the UI isn't minified.
## Initial Page Load
To decrease wait times for the user overall, the UI loads as much data on the initial page load as possible. After page load we wait for the schemas to load, because the schemas determine what the logged-in user has access to. After the schemas load, other resources can be loaded.
## List Views
List views can become slow to load when the UI attempts to load too much information. For example, a list of ingresses should not separately fetch services for each item in the list.
## Deferring Duplicate Requests
In `plugins/steve/actions.js`, if there are multiple requests for the same URL including the same path and headers, the store will recognize that a similar request already exists. Instead of making another request, it will defer it, and at the end it will only send one API call. This works for all resources in general.
# Pagination
Pagination doesn't help performance. Getting pages from etcd is slower than getting all the data at once because when you request paginated data from etcd, it gets all of the data and then throws away the data you didn't ask for. So requesting multiple pages is slower than requesting everything in one page.
The UI renders pages for display purposes only.
## Streaming
When the server responds with a large JSON object, the user might have to wait a long time for the entire object, so we split it into separate documents. If we stream the data we can start parsing data earlier.
Vince built a streaming parser that works a little faster than loading large JSON objects. However, it is currently disabled for two reasons:
- QA reported that the streaming caused a performance bug in Chrome.
- The performance benefit of streaming in Rancher was modest because a lot of wait time in the UI was due to waiting for a response to begin. The gain wouldn't be large unless the backend implemented it all the way down to etcd, which they may not do.
The code that supports streaming is in `plugins/steve/actions.js`. Only the Steve API supports streaming. The `supportsStream` properties in `store/index.js` have been set to false. They could be turned on again if the bug is fixed, but because the back end doesn't stream directly from etcd, the performance gain would not be large.

44
docs/developer/products-and-navigation.md Normal file
View File

@ -0,0 +1,44 @@
# Products and Navigation
Details on products such as Cluster Management, Fleet and Harvester are defined in `config/product`. For each product, we use the `product(options)` function to define whether you can remove it and what store is used to get resources for that product. For example, `config/product/explorer` defines how types are grouped and weighted in Cluster Explorer.
## Product Configuration
Products are top-level features that are reached via the header top left menu. Some are built in, such as `Cluster Explorer`, `Apps & Marketplace`, and `Users & Authentication`. Some are enabled only after installing the required Helm charts via `Apps & Marketplace`.
Configuration for each product can be found in `/config/product`. In the product configuration,
- `basicType()` indicates resources that are always shown in the side nav for the product, such as Services and Ingresses. Basic types are shown even if the number of them is 0, while other resources (such as the types listed under **More** in Cluster Explorer) are only included in the navigation if there is at least one of them.
- `ignoreType()` is used for types that were deprecated or hidden.
- `mapGroup()` maps Kubernetes API groups to more human-readable names.
- `configureType()` disables create for special types such as node types or Jobs because Jobs are not mutateable in Kubernetes. All of the possible types are defined in the `type-map/optionsFor` action.
- `headers()` defines headers shown in the list view for the resource. For basic cases you can define table headers in the product config. For more complicated cases, you can define a custom list component.
- `weightGroup()`/`weightType()` Sets the position of the group/type for this product.
These settings are stored in the `type-map` section of the store and manipulated with functions in `/store/type-map.js`. More docs for these functions are at the top of the `type-map.js` file.
## Building the Side Navigation
The side navigation bar is built by a function called `getTree` which is in `store/type-map.js`. `getTree` can be called in multiple modes. It takes a list of all types and returns the ones that match the condition of the mode.
`getTree` can be run in the following modes:
- `basic` matches data types that should always be shown even if there are 0 of them.
- `used` matches the data types where there are more than 0 of them in the current set of namespaces.
- `all` matches all types.
- `favorite` matches starred types.
You can specify if you want resources to be filtered by namespace or if all resources in the cluster should be shown.
## Counting Resources by Type
Steve keeps a count of every type in memory at `v1/counts`. This endpoint gives us a count of each type broken down by namespace and state, which allows the side nav to show a preview of how many resources of each type there are in the currently active namespace(s). Currently we don't use the count of resources broken down by state.
Note: While the side nav typically limits how many resources are shown so that the user is not overwhelmed, you can see all resources by clicking the magnifying glass in the top nav.
## Virtual and Spoofed Resource Types
The side nav is populated by resource types that have been applied to the current product. Virtual Types are a way to add additional menu items. These are purely for adding navigation and do not support tables or details views. Examples of virtual types can be found by searching for `virtualType`. For instance the `Users & Authentication` product has a virtual type of 'config' to show the `Auth Providers` page.
Spoofed Types, like virtual types, add menu items but also define a spoofed schema and a `getInstances` function. The latter provides a list of objects of the spoofed type. This allows the app to then make use of the generic list, detail, edit, etc pages used for standard types.

2
plugins/steve/rehydrate-all.js
View File

@ -1,6 +1,8 @@
const MAX_DEPTH = 20;
export default function() {
// In the rehydration process, a block of JSON from the server
// is converted into classes.
this.nuxt.hook('vue-renderer:ssr:context', (context) => {
if ( context.nuxt.data ) {
recurse(context.nuxt.data);

8
store/type-map.js
View File

@ -483,7 +483,13 @@ export const getters = {
getTree(state, getters, rootState, rootGetters) {
return (productId, mode, allTypes, clusterId, namespaceMode, namespaces, currentType, search) => {
// modes: basic, used, all, favorite
// getTree has four modes:
// - `basic` matches data types that should always be shown even if there
// are 0 of them.
// - `used` matches the data types where there are more than 0 of them
// in the current set of namespaces.
// - `all` matches all types.
// - `favorite` matches starred types.
// namespaceMode: 'namespaced', 'cluster', or 'both'
// namespaces: null means all, otherwise it will be an array of specific namespaces to include
const isBasic = mode === BASIC;