[
https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016155#comment-17016155
]
Jacob Ward edited comment on AIRFLOW-6556 at 1/15/20 5:09 PM:
--------------------------------------------------------------
Here's a list of issues myself and my team have noticed. I'll add more as I
notice them.
* [Kubernetes|https://airflow.apache.org/docs/stable/kubernetes.html]:
** An explanation of how the KubernetesExecutor (KE) and KubernetesPodOperator
(KPO) work.
** An explanation of the difference between the KE & KPO (I see this question
and confusion arise a lot in slack).
** An explanation of exactly what the [kubernetes] config options are used for
with the KE (something that I have only just started to understand is that
these config options mostly apply to the workers, since the scheduler does not
_have_ to run inside the cluster with KE).
** (Minor) The KPO hyperlink on the Kubernetes doc page sends you to the KE
page. Also the links on this page send you to readthedocs.io
* Some information [(possibly
here)|https://airflow.apache.org/docs/stable/concepts.html?highlight=trigger%20rule#dag-assignment]
about how assigning operators to dags after creation means the default_args
aren't applied.
* In general I think the Concepts/Core Ideas section has a lot of interesting
and useful information, but since it is one long page it makes it harder to
find the information you need. I think this would be better split into several
pages with more information and examples for each concept.
* Some information on best practice, how to avoid common pitfalls, etc.
* [LocalExecutor is
missing|https://airflow.apache.org/docs/stable/executor/index.html] and some
general information on the architecture and how these Executors are supposed to
work would be useful. I often see new users getting confused by what the
Executor really is, and get this and operators mixed up at times.
* [Security|https://airflow.apache.org/docs/stable/security.html#viewer] -
What all the permissions are, and what does each one actually mean? E.g.
'can_show' is not descriptive enough to know exactly what it means.
* It may be covered by Kaxil's updates to the config documentation, but a page
on how new dags are picked up, parsed and stored, and what the DagBag is and it
interacts with/or is interacted with by the scheduler/webserver/db.
was (Author: jward):
Here's a list of issues myself and my team have noticed. I'll add more as I
notice them.
* [Kubernetes|https://airflow.apache.org/docs/stable/kubernetes.html]:
** An explanation of how the KubernetesExecutor (KE) and KubernetesPodOperator
(KPO) work.
** An explanation of the difference between the KE & KPO (I see this question
and confusion arise a lot in slack).
** An explanation of exactly what the [kubernetes] config options are used for
with the KE (something that I have only just started to understand is that
these config options mostly apply to the workers, since the scheduler does not
_have_ to run inside the cluster with KE).
** (Minor) The KPO hyperlink on the Kubernetes doc page sends you to the KE
page. Also the links on this page send you to readthedocs.io
* Some information [(possibly
here)|https://airflow.apache.org/docs/stable/concepts.html?highlight=trigger%20rule#dag-assignment]
about how assigning operators to dags after creation means the default_args
aren't applied.
* In general I think the Concepts/Core Ideas section has a lot of interesting
and useful information, but since it is one long page it makes it harder to
find the information you need. I think this would be better split into several
pages with more information and examples for each concept.
* Some information on best practice, how to avoid common pitfalls, etc.
* [LocalExecutor is
missing|https://airflow.apache.org/docs/stable/executor/index.html] and some
general information on the architecture and how these Executors are supposed to
work would be useful. I often see new users getting confused by what the
Executor really is, and get this and operators mixed up at times.
* [Security|https://airflow.apache.org/docs/stable/security.html#viewer] -
What all the permissions are, and what does each one actually mean? E.g.
'can_show' is not descriptive enough to know exactly what it means.
> Improving unclear and incomplete documentation
> ----------------------------------------------
>
> Key: AIRFLOW-6556
> URL: https://issues.apache.org/jira/browse/AIRFLOW-6556
> Project: Apache Airflow
> Issue Type: Improvement
> Components: documentation
> Affects Versions: master
> Reporter: Jacob Ward
> Assignee: Jarek Potiuk
> Priority: Trivial
>
> To help improve documentation it was discussed in the mailing list that users
> of Airflow should have somewhere to report missing, incomplete or unclear
> documentation. Any users who find this should comment on this ticket.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
