Skip to content

Commit

Permalink
Adding Warning Component in various docs
Browse files Browse the repository at this point in the history
Removing redundant warning from `tasks/workertype`

Remove redundant warning from `using/namespaces`
  • Loading branch information
vishakhanihore authored and outreachy committed Oct 2, 2019
1 parent 8ea54a8 commit ba71987
Show file tree
Hide file tree
Showing 6 changed files with 25 additions and 5 deletions.
3 changes: 3 additions & 0 deletions ui/docs/manual/access-control/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: API Access Control
order: 10
---
import Warning from 'taskcluster-ui/views/Documentation/components/Warning';

# API Access Control

Expand Down Expand Up @@ -29,5 +30,7 @@ There are some interesting semantics to `*` for roles, described in the design d
Each request is associated with a [`clientId`](/docs/manual/design/apis/hawk/clients).
This can indicate a record in the table of pre-defined clients, but much more commonly names a temporary credential such as that for a worker executing a task.

<Warning>
An important point to note is that API access control is based entirely on scopes and involves no notion of "identity" - no "users" or "accounts".
Client IDs are for logging and auditing purposes and are not used for access control.
</Warning>
3 changes: 3 additions & 0 deletions ui/docs/manual/design/conventions/actions/spec.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Action Specification
order: 20
---
import SchemaTable from 'taskcluster-ui/components/SchemaTable'
import Warning from 'taskcluster-ui/views/Documentation/components/Warning';

# Action Specification

Expand Down Expand Up @@ -306,9 +307,11 @@ limit what the resulting task does.
The payload of the `triggerHook` call is given by the `hookPayload` property,
which is rendered using JSON-e with the context described above.

<Warning>
Note that the result of rendering `hookPayload` becomes the *context* for
another JSON-e rendering performed by the hooks service. Do not confuse the
two operations!
</Warning>

## Formal Specification

Expand Down
7 changes: 5 additions & 2 deletions ui/docs/manual/tasks/priority.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,14 @@ filename: tasks/priority.mdx
title: Priority
order: 25
---
import Warning from 'taskcluster-ui/views/Documentation/components/Warning';

Each task has a `priority` field giving its relative priority, chosen from a
small set of named priorities. When several tasks are pending in the same
queue, those with the highest priority will be executed first.

Note that this can result in starvation: if there are enough tasks at a given
<Warning>
Please note that this can result in starvation: if there are enough tasks at a given
priority to keep all available workers busy, then no tasks of lower priority
will run.
will run.
</Warning>
5 changes: 4 additions & 1 deletion ui/docs/manual/tasks/scopes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ filename: tasks/scopes.mdx
title: Task Scopes
order: 60
---
import Warning from 'taskcluster-ui/views/Documentation/components/Warning';

Taskcluster permissions are represented by "scopes", covered in more detail in
[the design section](/docs/manual/design/apis/hawk/scopes). For this section, it
Expand All @@ -25,6 +26,8 @@ In fact, several scope sets must be satisfieid to create a task:
routes, priorities, and `schedulerId`.
* The task's `scopes` property

*NOTE*: this means that scopes for a task must often be configured in two places. For example, to use a scope `secrets:get:org-project-test-creds`, a task associated with a github project would need:
<Warning>
This means that scopes for a task must often be configured in two places. For example, to use a scope `secrets:get:org-project-test-creds`, a task associated with a github project would need:
* the scope satisfied by a role such as `repo:github.com/org/project:branch:master`
* the same scope listed in the task's `scopes` property
</Warning>
5 changes: 4 additions & 1 deletion ui/docs/manual/tasks/workertypes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ filename: tasks/workertypes.mdx
title: Worker Types
order: 20
---
import Warning from 'taskcluster-ui/views/Documentation/components/Warning';

Workers execute tasks, but there are many types of workers. A task specifies a
single "worker type" by which it should be executed, using the two-part
Expand All @@ -12,8 +13,10 @@ both identifiers. Thus `gcp-provisioner/persona-build` and
`rackspace-provisioner/persona-build` are completely different worker types,
despite sharing the same `workerType` identifier.

*NOTE*: [RFC#145](https://github.com/taskcluster/taskcluster-rfcs/pull/145) addresses this confusion by introducing the term `taskQueueId` to name the queue in which a task is stored.
<Warning>
[RFC#145](https://github.com/taskcluster/taskcluster-rfcs/pull/145) addresses this confusion by introducing the term `taskQueueId` to name the queue in which a task is stored.
This RFC is not yet fully implemented, so the Queue API still uses identifiers `provisionerId` and `workerType`.
</Warning>

Workers of the same worker type all consume tasks from a single queue, as
[described later](/docs/manual/task-execution/queues), and as such are
Expand Down
7 changes: 6 additions & 1 deletion ui/docs/manual/using/namespaces.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: Namespaces
order: 30
---
import Warning from 'taskcluster-ui/views/Documentation/components/Warning';

# Namespaces

Expand Down Expand Up @@ -119,11 +120,13 @@ Artifact names are, by convention, slash-separated.
This namespace enables tasks to persist data that is only readable by a single user (typically the user that submitted it), such as loaner credentials.
Access to such artifacts is not automatically granted, but such a grant could be accomplished by adding scope `queue:get-artifact:login-identity/<..>` to role `login-identity:*`.

Note, highly confidential data should not be stored in unencrpyted taskcluster
<Warning>
Highly confidential data should not be stored in unencrpyted taskcluster
artifacts, since they are only protected by a single (fallible) system. If
highly sensitive data needs to be persisted, it is recommended to encrypt data
using the public key of a key-pair whose private key has been highly secured,
in order that at least two independent systems protect the data.
</Warning>

---

Expand Down Expand Up @@ -259,6 +262,8 @@ The scopes cover:
* secrets `project/<project>/*`
* index namespaces `project.<project>.*`

<Warning>
In some cases, projects need additional scopes.
To do so, create a role `project:<project>:grants/<grantName` containing the desired scopes.
This role can then be assumed where necessary, or project admins can use it to grant specific scopes as desired.
</Warning>

0 comments on commit ba71987

Please sign in to comment.