Skip to content

docs: more language refresh #556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: more language refresh #556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 15 additions & 16 deletions lit/docs/auth.lit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
\use-plugin{concourse-docs}
\split-sections

A single Concourse installation can accomodate many projects and users.
A single Concourse installation can accommodate many projects and users.

Pipelines, builds, and all other user data are owned by \italic{teams}. A team
is just a conceptual owner and a separate namespace, tied to an authorization
config. For example, a team may authorize all members of the \code{concourse}
is simply a conceptual owner and separate namespace, tied to an authorization
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is BOTH a conceptual owner and separate namespace

configuration. For example, a team may authorize all members of the \code{concourse}
GitHub organization to be a \reference{team-member-role}{member}.

When a user authenticates, each team's authorization config is checked against
Expand All @@ -29,37 +29,36 @@ access control for future requests.
users, see \reference{fly-expose-pipeline}.

Even with a pipeline exposed, all build logs are hidden by default. This is
because CI jobs are prone to leaking credentials and other...unsavory
information. After you've determined that a job's builds should be safe for
public consumption, you can set \reference{schema.job.public}{\code{public: true}}
on the job in your pipeline.
because CI jobs may leak credentials and other sensitive information.
After you've determined that a job's builds are safe for public consumption,
you can set \reference{schema.job.public}{\code{public: true}} on the job
in your pipeline.
}

\section{
\title{Security Caveats}{teams-caveats}

At present, teams only provide \italic{trusted multi-tenancy}. This means it
At present, teams only provide \italic{trusted multi-tenancy}. This means they
should be used for cases where you know and trust who you're allowing access
into your Concourse cluster.

There are a few reasons it'd be a bad idea to do otherwise:
There are a few reasons it would be a bad idea to do otherwise:

\list{
Any team can run builds with \reference{schema.task.privileged} tasks. A bad
actor in the mix could easily use this to harm your workers and your
Any team can run builds with \reference{schema.task.privileged} tasks. A malicious
actor could easily use this to harm your workers and your
cluster.

In the future, we'll probably have this as a flag on a team, indicating
In the future, we'll likely add this as a flag on a team, indicating
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the future, we plan on adding this

whether they're permitted to run privileged builds.
}{
There are no networking restrictions in place, and traffic to and from the
workers is currently unencrypted and unauthorized. Anyone could run a task
that does horrible things to your worker's containers, possibly stealing
that does harmful things to your worker's containers, potentially stealing
sensitive information.

This can be remedied with configuration specified on Garden to restrict
access to the internal network, but this is not detailed in our docs, and
we'll probably want to find a better answer than configuration in the
future.
we'll likely want to find a better solution in the future.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we're actively considering better approaches to this problem.

}
}
}
84 changes: 43 additions & 41 deletions lit/docs/builds.lit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

\use-plugin{concourse-docs}

A build is an execution of a \italic{build plan}, which is either
A build is an execution of a \italic{build plan}, which is either:

\list{
configured as a sequence of \reference{steps}{steps} in a \reference{jobs}{job}
Expand All @@ -14,37 +14,37 @@ A build is an execution of a \italic{build plan}, which is either

Containers and volumes are created as \reference{get-step}s,
\reference{put-step}s, and \reference{task-step}s run. When a build completes
successfully, these containers go away.
successfully, these containers are removed.

A failed build's containers and volumes are kept around so that you can debug
the build via \reference{fly-intercept}. If the build belongs to a
\reference{jobs}{job}, the containers will go away when the next build starts.
If the build is a one-off, its containers will be removed immediately, so make
sure you intercept while it's running, if you want to debug.
For failed builds, containers and volumes are preserved to allow debugging
via \reference{fly-intercept}. If the build belongs to a
\reference{jobs}{job}, the containers will be removed when the next build starts.
If the build is a one-off, its containers will be removed immediately, so make sure
you intercept while it's running if you want to debug.

\table-of-contents

\section{
\title{Rerunning a Build}{build-rerunning}

Concourse supports build rerunning, which means to run a new build using the
Concourse supports build rerunning, which means running a new build using the
exact same set of input versions as the original build. There are two ways to
rerun a build: through the web UI on the builds page and through the
\reference{fly-rerun-build}.
\reference{fly-rerun-build} command.

When a build is rerun, it will create a new build using the name of the
When a build is rerun, it creates a new build using the name of the
original build with the rerun number appended to it, e.g. \code{3.1} for the
first rerun of build \code{3}.

Rerun builds are ordered chronologically after the original build, rather
than becoming a new "latest" build. Similarly, when the scheduler is
resolving \reference{schema.get.passed}{\code{passed}} constraints
that reference a job with rerun builds, those rerun builds are
processed in this same order. This ensures that the versions, which made it
through a rerun build, do not become the new "latest versions". Instead, they
processed in this same order. This ensures that versions which made it
through a rerun build do not become the new "latest versions". Instead, they
act as if the original build had succeeded at its point in the build history.

This may sound a little confusing, but the summary is that reruns should
This may sound a little confusing, but the key point is that reruns should
behave as if they replace the original failed build.

\section{
Expand All @@ -56,11 +56,11 @@ sure you intercept while it's running, if you want to debug.
with.

This means that if the \reference{schema.job.plan} has changed in a way
that is backwards-incompatible, the rerun build may error. For example, if
that is backwards-incompatible, the rerun build may fail. For example, if
a new input is added, its version will not be available as the original
build did not use it.

There are future plans to have reruns execute the exact build plan from the
There are plans to have reruns execute the exact build plan from the
original build. If you are interested in tracking the progress for the
second pass at rerunning builds - or contributing yourself! - the project
epic is called \link{Build Lifecycle
Expand All @@ -86,7 +86,7 @@ sure you intercept while it's running, if you want to debug.
This can be useful for periodically monitoring the state of a job. The output
also works well with tools like \code{awk} and \code{grep}.

By default the most recent 50 builds are shown. To see more builds, use
By default, the most recent 50 builds are shown. To see more builds, use
the \code{-c} flag, like so:

\codeblock{bash}{{
Expand All @@ -97,16 +97,16 @@ sure you intercept while it's running, if you want to debug.
\section{
\title{\code{fly intercept}}{fly-intercept}

Sometimes it's helpful to connect to the machine where tasks run. This way you
can either profile or inspect tasks, or see the state of the machine at the
end of a run. Due to Concourse running tasks in containers on remote
machines this would typically be hard to access.
Sometimes it's helpful to connect to the machine where tasks run. This allows you
to profile or inspect tasks, or see the state of the machine at the
end of a run. Since Concourse runs tasks in containers on remote
machines, these would typically be difficult to access.

To this end, there is a \code{fly intercept} command that will give you an
The \code{fly intercept} command gives you an
interactive shell inside the specified container. Containers are identified
by a few things, so you may need to specify a few flags to hone down the
results. If there are multiple containers that the flags could refer to, an
interactive prompt will show up allowing you to disambiguate.
by several attributes, so you may need to specify multiple flags to narrow down the
results. If there are multiple matching containers, an
interactive prompt will appear allowing you to select one.

For example, running the following will run a task and then enter the
finished task's container:
Expand All @@ -118,15 +118,15 @@ sure you intercept while it's running, if you want to debug.

\aside{
When intercepting a task running on a Windows worker, you will need to
specifically tell fly to to run \code{powershell}:
specifically tell fly to run \code{powershell}:

\codeblock{bash}{{
$ fly -t example intercept powershell
}}
}

Containers are around for a short time after a build finishes in order to
allow people to intercept them.
Containers remain available for a short time after a build finishes to
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we know how long? Is it configurable?

allow for interception.

You can also intercept builds that were run in your pipeline. By using
\code{--job}, \code{--build}, and \code{--step} you can intercept a specific
Expand All @@ -138,11 +138,11 @@ sure you intercept while it's running, if you want to debug.
}}

Note that \code{--build} can be omitted, and will default to the most recent
build of the job. One-off builds can be reached by passing in their build ID
to \code{--build} which can be found on the build list page.
build of the job. One-off builds can be reached by passing their build ID
to \code{--build}, which can be found on the build list page.

The \code{--step} flag can also be omitted; this will let you pick the step
interactively, if you don't know the exact name.
The \code{--step} flag can also be omitted; this will let you select the step
interactively if you don't know the exact name.

Resource checking containers can also be intercepted with \code{--check} or
\code{-c}:
Expand All @@ -157,7 +157,7 @@ sure you intercept while it's running, if you want to debug.
current build's task, even as the "current build" changes.

The working directory and any relevant environment variables (e.g. those
having come from \reference{schema.task.params}) used by the original process will
from \reference{schema.task.params}) used by the original process will
also be used for the process run by intercept.
}

Expand All @@ -178,26 +178,26 @@ sure you intercept while it's running, if you want to debug.
\title{\code{fly watch}}{fly-watch}

Concourse emits streaming colored logs on the website, but it can be helpful
to have the logs available to the command line (e.g. so that they can be
to have the logs available in the command line (e.g. so they can be
processed by other commands).

The \code{watch} command can be used to do just this. You can also view
The \code{watch} command can be used for this purpose. You can view
builds that are running in your pipeline, or builds that have already
finished.

Note that unlike \reference{fly-execute}, killing \code{fly watch} via
\code{SIGINT} or \code{SIGTERM} will \italic{not} abort the build.

To watch the most recent one-off build, just run \code{fly watch} with no
arguments. To watch a specific build (one-off or no), pass \code{--build}
To watch the most recent one-off build, run \code{fly watch} with no
arguments. To watch a specific build (one-off or not), pass \code{--build}
with the ID of the build to watch. This ID is available at the start of
\reference{fly-execute}'s output or by browsing to the builds list in the web
UI.

By using the \code{--job} and \code{--build} flags you can pick out a
By using the \code{--job} and \code{--build} flags, you can select a
specific build of a job to watch. For example, the following command will
either show the archived logs for an old build, if it has finished running, or
it will stream the current logs, if the build is still in progress.
either show the archived logs for an old build if it has finished running, or
it will stream the current logs if the build is still in progress.

\codeblock{bash}{{
$ fly -t example watch --job my-pipeline/tests --build 52
Expand All @@ -206,5 +206,7 @@ sure you intercept while it's running, if you want to debug.
If the \code{--job} flag is specified and \code{--build} is omitted, the most
recent build of the specified job will be selected.

If there is a mismatch between the \code{fly} and \code{web} versions, it is possible to run into \code{failed to parse next event: unknown event type} error. The \code{--ignore-event-parsing-errors} flag can be passed to ignore such errors.
}
If there is a mismatch between the \code{fly} and \code{web} versions, you may encounter
a \code{failed to parse next event: unknown event type} error. The \code{--ignore-event-parsing-errors}
flag can be passed to ignore such errors.
}
12 changes: 6 additions & 6 deletions lit/docs/config.lit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

\use-plugin{concourse-docs}

Concourse configuration for things like \reference{pipelines} and
\reference{tasks} is done through declarative
Concourse configuration for features like \reference{pipelines} and
\reference{tasks} is managed through declarative
\link{YAML}{https://en.wikipedia.org/wiki/YAML} files.

Concourse configuration supports basic variable substitution by way of
Concourse configuration supports basic variable substitution using
\reference{vars}{\code{((vars))}}. There is no built-in support for
fancier templating constructs, e.g. loops and conditionals; users are free to
use whatever templating system they like.
more advanced templating constructs such as loops and conditionals; users are free to
use whatever templating system they prefer.

\table-of-contents

\include-section{config/yaml.lit}
\include-section{config/basic-schemas.lit}
\include-section{config/basic-schemas.lit}
16 changes: 8 additions & 8 deletions lit/docs/getting-started.lit
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
\title{Getting Started}

This tutorial will guide you through the basics of creating Concourse
This tutorial guides you through the basics of creating Concourse
pipelines. You will use a local instance of Concourse running on your machine to
run pipelines.

Before getting started you should have the following installed:
Before getting started, ensure you have the following installed:

\list{
\link{Docker}{https://docs.docker.com/get-docker/}
Expand All @@ -13,17 +13,17 @@ Before getting started you should have the following installed:
}

This tutorial assumes you understand what Linux containers are and how to work
with them. If you know what a Dockerfile is and how to make your own then you're
probably good to jump into this tutorial. If you're not familiar with Linux
containers then you may want to \link{get started with
Docker}{https://docs.docker.com/get-started/} first before diving into this
with them. If you know what a Dockerfile is and how to create one, you're
probably ready for this tutorial. If you're not familiar with Linux
containers, we recommend \link{getting started with
Docker}{https://docs.docker.com/get-started/} before diving into this
tutorial.

It will also help if you know how to read YAML. We have a quick
\reference{intro-to-yaml} if you're not familiar with the syntax.

\aside{
If you have any feedback for this tutorial please share it in \link{this
If you have any feedback for this tutorial, please share it in \link{this
GitHub discussion}{https://github.com/concourse/concourse/discussions/7353}
}

Expand All @@ -34,4 +34,4 @@ It will also help if you know how to read YAML. We have a quick
\include-section{getting-started/quickstart.lit}
\include-section{getting-started/hello-world.lit}
\include-section{getting-started/inputs-outputs.lit}
\include-section{getting-started/resources.lit}
\include-section{getting-started/resources.lit}
12 changes: 6 additions & 6 deletions lit/docs/how-to-guides.lit
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
\title{How-To Guides}

The following pages are guides that show how to accomplish certain workflows
within Concourse. Most of the guides will use specific images but you are in no
way limited to or forced to use these images to accomplish the same task. There
are many ways to accomplish the same thing in Concourse, so don't let these
guides limit you in what you think is possible with Concourse.
The following pages provide guides that show how to accomplish specific workflows
within Concourse. Most guides use specific images, but you are not limited to
or required to use these images to accomplish the same tasks. There are many ways
to accomplish the same goal in Concourse, so don't let these guides limit your
understanding of what's possible with Concourse.

\split-sections
\table-of-contents

\include-section{./guides/pipeline-guides.lit}
\include-section{./guides/git.lit}
\include-section{./guides/container-images.lit}
\include-section{./guides/container-images.lit}
Loading