Version imprimable multipages. Cliquer ici pour imprimer.

Retour à la version régulière.

Vue d'ensemble des documents de référence

Documentation références Kubernetes

Une grande partie de la documentation de référence de Kubernetes est générée à partir du code source de Kubernetes, à l'aide de scripts. Les rubriques de cette section expliquent comment générer ce type de contenu.

1 - Génération de documentation de référence pour l'API Kubernetes

Génération documentation référence API Kubernetes

Cette page montre comment mettre à jour les documents de référence générés automatiquement pour l'API Kubernetes.

Pré-requis

Vous devez avoir ces outils installés:

Votre variable d'environnement $GOPATH doit être définie et l'emplacement de etcd doit être dans votre variable d'environnement $PATH.

Vous devez savoir comment créer une pull request dans un dépôt GitHub. Généralement, cela implique la création d'un fork du dépôt. Pour plus d'informations, voir Créer une Pull Request de documentation et GitHub Standard Fork & Pull Request Workflow.

Généralités

La mise à jour de la documentation de référence de l'API Kubernetes est un processus en deux étapes:

  1. Générez une spécification OpenAPI à partir du code source de Kubernetes. Les outils pour cette étape sont kubernetes/kubernetes/hack.

  2. Générez un fichier HTML à partir de la spécification OpenAPI. Les outils pour cette étape sont à kubernetes-incubator/reference-docs.

Obtenir trois dépôts

Si vous ne possédez pas déjà le dépôt kubernetes/kubernetes, téléchargez-le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Déterminez le dépôt de base de votre clone de kubernetes/kubernetes. Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre dépôt de base est $GOPATH/src/github.com/kubernetes/kubernetes. Les étapes restantes se réfèrent à votre répertoire de base en tant que <k8s-base>.

Si vous ne possédez pas déjà le dépôt kubernetes/website, obtenez-le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website

Déterminez le répertoire de base de votre dépôt kubernetes/website. Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre répertoire de base est $GOPATH/src/github.com/kubernetes/website. Les étapes restantes se réfèrent à votre répertoire de base en tant que <web-base>.

Si vous n'avez pas déjà le dépôt kubernetes-incubator/reference-docs, obtenez-le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs

Déterminez le répertoire de base de votre dépôt kubernetes-incubator/reference-docs. Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre répertoire de base est $GOPATH/src/github.com/kubernetes-incubator/reference-docs. Les étapes restantes se réfèrent à votre répertoire de base en tant que <rdocs-base>.

Modification du code source de Kubernetes

La documentation de référence de l'API Kubernetes est générée automatiquement à partir d'une spécification OpenAPI, générée à partir du code source de Kubernetes. Si vous souhaitez modifier la documentation de référence, la première étape consiste à modifier un ou plusieurs commentaires dans le code source de Kubernetes.

Modification des commentaires dans le code source

Note: Les étapes suivantes sont un exemple et non une procédure générale. Les détails seront différents dans votre situation.

Voici un exemple d'édition d'un commentaire dans le code source de Kubernetes.

Dans votre dépôt local kubernetes/kubernetes, vérifiez la branche master et assurez-vous qu'elle est à jour:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Supposons que ce fichier source dans la branche principale ait la typo "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

Dans votre environnement local, ouvrez types.go et remplacez "atmost" par "at most".

Vérifiez que vous avez modifié le fichier:

git status

La sortie montre que vous êtes sur la branche master et que le fichier source types.go a été modifié:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Valider votre fichier édité

Exécutez git add et git commit pour valider les modifications que vous avez apportées jusqu'à présent. Dans l'étape suivante, vous ferez un deuxième commit. Il est important de séparer vos modifications en deux commits.

Génération de la spécification OpenAPI et des fichiers associés

Allez sur <k8s-base> et exécutez ces scripts:

hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Exécutez git status pour voir ce qui a été généré.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Voir le contenu de api/openapi-spec/swagger.json pour vous assurer que la faute de frappe est corrigée. Par exemple, vous pouvez exécuter git diff -a api/openapi-spec/swagger.json. Ceci est important, car swagger.json sera l’entrée de la seconde étape du processus de génération de doc.

Exécutez git add et git commit pour valider vos modifications. Vous avez maintenant deux validations: une avec le fichier types.go édité et une avec les spécifications OpenAPI générées et les fichiers associés. Gardez ces deux commits séparés. C'est-à-dire, ne faites pas un squash de vos commits.

Soumettez vos modifications en tant que pull request à la branche principale du dépôt kubernetes/kubernetes. Surveillez votre pull request, et répondre aux commentaires des relecteurs au besoin. Continuez à surveiller votre pull request jusqu'à ce qu'il ait été mergé.

PR 57758 est un exemple de demande d'extraction qui corrige une faute de frappe dans le code source de Kubernetes.

Note: Il peut être difficile de déterminer le fichier source correct à modifier. Dans l'exemple précédent, le fichier source faisant autorité se trouve dans le répertoire staging du dépôt kubernetes/kubernetes. Mais dans votre cas, le répertoire staging pourrait ne pas être l’endroit où trouver la source faisant autorité. Pour vous guider, consultez les fichiers README dans le dépôt kubernetes/kubernetes et dans le dépôt kubernetes/apiserver.

Cherry picking votre commit dans une branche release

Dans la section précédente, vous avez modifié un fichier dans la branche principale, puis exécuté des scripts pour générer une spécification OpenAPI et les fichiers associés. Vous avez ensuite soumis vos modifications dans une demande d'extraction à la branche maître du dépôt kubernetes/kubernetes. Supposons maintenant que vous souhaitiez faire un backport de votre modification dans une branche de publication. Par exemple, supposons que la branche principale soit utilisée pour développer Kubernetes version 1.10 et que vous souhaitiez faire un backport de votre modification dans la branche de la version 1.9.

Rappelez-vous que votre pull request a deux commits: un pour l'édition types.go et un pour les fichiers générés par des scripts. La prochaine étape consiste à proposer un cherry pick de votre premier commit dans la branche release-1.9. L'idée est de cherry pick le commit qui a édité types.go, mais pas le commit qui a pour résultat l'exécution des scripts. Pour les instructions, voir Proposer un Cherry Pick.

Note: Proposer un cherry pick nécessite que vous ayez la permission de définir un label et un milestone dans votre pull request. Si vous ne disposez pas de ces autorisations, vous devrez travailler avec une personne pouvant définir les labels et milestones pour vous.

Quand vous avez une pull request en place pour cherry picking votre seul commit dans la branche release-1.9, l’étape suivante consiste à exécuter ces scripts dans la branche release-1.9 de votre environnement local.

hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Maintenant, ajoutez un commit à votre cherry-pick pull request qui contient la spécification OpenAPI récemment générée et les fichiers associés. Surveillez votre pull request jusqu'à ce qu'elle soit mergée dans la branche release-1.9.

À ce stade, la branche master et la branche release-1.9 ont votre fichier types.go mis à jour et un ensemble de fichiers générés qui reflètent les modifications apportées à types.go. Notez que la spécification OpenAPI générée et les autres fichiers générés dans la branche release-1.9 ne sont pas nécessairement identiques aux fichiers générés dans la branche master. Les fichiers générés dans la branche release-1.9 contiennent des éléments API uniquement à partir de Kubernetes 1.9. Les fichiers générés dans la branche maître peuvent contenir des éléments de l'API qui ne sont pas dans la version 1.9, mais sont en cours de développement pour la version 1.10.

Génération des documents de référence publiés

La section précédente a montré comment modifier un fichier source, puis générer plusieurs fichiers, y compris api/openapi-spec/swagger.json dans le dépôt kubernetes/kubernetes.

Cette section montre comment générer la documentation de référence de l'API Kubernetes publiée, qui est générée par les outils de kubernetes-incubator/reference-docs. Ces outils prennent le fichier api/openapi-spec/swagger.json comme entrée.

Modification du Makefile dans kubernetes-incubator/reference-docs

Aller à <rdocs-base>, et ouvrez Makefile pour l'édition:

Définissez K8SROOT dans le répertoire de base de votre dépôt local kubernetes/kubernetes. Définissez WEBROOT sur le répertoire de base de votre référentiel kubernetes/website. Définissez MINOR_VERSION sur la version mineure de la documentation que vous souhaitez créer. Par exemple, si vous souhaitez créer des documents pour Kubernetes 1.9, définissez MINOR_VERSION sur 9. Enregistrez et fermez Makefile.

Copier la spécification OpenAPI

Le code de génération de document nécessite une copie locale de la spécification OpenAPI pour l'API Kubernetes. Allez sur <k8s-base> et vérifiez la branche qui a la spécification OpenAPI que vous voulez utiliser. Par exemple, si vous souhaitez générer des documents pour Kubernetes 1.9, consultez la branche release-1.9.

Retournez à <rdocs-base>. Entrez la commande suivante pour copier la spécification OpenAPI à partir du dépôt kubernetes/kubernetes vers un répertoire local:

make updateapispec

La sortie montre que le fichier a été copié:

cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json

Construire l'image brodocs

Le code de génération de doc nécessite l'image Docker pwittrock/brodocs.

Cette commande crée l’image Docker pwittrock/brodocs. Il essaie également de transmettre l’image à DockerHub, mais c’est acceptable si cette étape échoue. Tant que vous avez l'image localement, la génération de code peut réussir.

make brodocs

Vérifiez que vous avez l'image brodocs:

docker images

La sortie affiche pwittrock / brodocs comme l'une des images disponibles:

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
pwittrock/brodocs   latest              999d34a50d56        5 weeks ago         714MB

Exécuter le code de génération de doc

Générez et exécutez le code de génération de doc. Vous devrez peut-être exécuter la commande en tant que root:

cd <rdocs-base>
make api

Localiser les fichiers générés

Ces deux fichiers sont le résultat d’une construction réussie. Vérifiez qu'ils existent:

  • <rdocs-base>/gen-apidocs/generators/build/index.html
  • <rdocs-base>/gen-apidocs/generators/build/navData.js

Copier les documents générés dans le dépôt kubernetes/website

Les sections précédentes ont montré comment modifier un fichier source Kubernetes, générer une spécification OpenAPI, puis générer une documentation de référence pour la publication.

Cette section explique comment copier les documents générés sur le dépôt kubernetes/website. Les fichiers dans le dépôt kubernetes/website sont publiés sur le site web kubernetes.io. En particulier, le fichier généré index.html est publié ici.

Entrez la commande suivante pour copier les fichiers générés dans votre dépôt local kubernetes/website:

make copyapi

Allez à la base de votre dépôt local kubernetes/kubernetes, et regardez quels fichiers ont été modifiés:

cd <web-base>
git status

La sortie montre les fichiers modifiés:

On branch master
...
   modified:   docs/reference/generated/kubernetes-api/v1.9/index.html

Dans cet exemple, un seul fichier a été modifié. Rappelez-vous que vous avez généré les deux index.html et navData.js. Mais apparemment le généré navata.js n'est pas différent du navData.js c'était déjà dans le dépôt kubernetes/website.

Dans <web-base> executez git add et git commit pour enregistrer le commit du changement.

Soumettez vos modifications en tant que pull request au dépôt kubernetes/website. Surveillez votre pull request, et répondez aux commentaires des relecteurs au besoin. Continuez à surveiller votre pull request jusqu'à ce qu'elle ait été mergée.

Quelques minutes après que votre pull request soit fusionnée, vos modifications seront visibles dans la documentation de référence publiée.

A suivre

2 - Génération de la documentation de référence pour l'API de fédération Kubernetes

Federation Référence API Kubernetes Documentation

Cette page montre comment générer automatiquement des pages de référence pour l'API de fédération Kubernetes.

Pré-requis

  • Vous devez avoir Git installé.

  • Vous devez avoir Golang version 1.9.1 ou ultérieur installé, et votre variable d'environnement $GOPATH doit être définie.

  • Vous devez avoir Docker installé.

  • Vous devez savoir comment créer une pull request sur un dépôt GitHub. Généralement, cela implique la création d'un fork du dépôt. Pour plus d'informations, voir Création d'une pull request de documentation.

Exécution du script update-federation-api-docs.sh

Si vous ne possédez pas déjà le code source de la fédération Kubernetes, procurez-vous-le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/federation

Déterminez le répertoire de base de votre dépôt local kubernetes/federation. Par exemple, si vous avez suivi l'étape précédente pour obtenir le code source de la fédération, votre répertoire de base est $GOPATH/src/github.com/kubernetes/federation. Les étapes restantes se réfèrent à votre répertoire de base en tant que <fed-base>.

Exécutez le script de génération de documentation:

cd <fed-base>
hack/update-federation-api-reference-docs.sh

Le script exécute le k8s.gcr.io/gen-swagger-docs image pour générer cet ensemble de documents de référence:

  • /docs/api-reference/extensions/v1beta1/operations.html
  • /docs/api-reference/extensions/v1beta1/definitions.html
  • /docs/api-reference/v1/operations.html
  • /docs/api-reference/v1/definitions.html

Les fichiers générés ne sont pas publiés automatiquement. Ils doivent être copiés manuellement sur dépôt kubernetes/website.

Ces fichiers sont publiés à kubernetes.io/docs/reference:

A suivre

3 - Génération de pages de référence pour les composants et les outils Kubernetes

Cette page montre comment utiliser l'outil update-importer-docs pour générer une documentation de référence pour les outils et les composants des dépôts Kubernetes et Federation.

Pré-requis

  • Vous avez besoin d'une machine qui exécute Linux ou macOS.

  • Ces logiciels doivent être installés:

  • Votre variable d'environnement $GOPATH doit être définie.

  • Vous devez savoir comment créer une pull request sur un dépôt GitHub. Cela implique généralement la création d’un fork d'un dépôt. Pour plus d'informations, consultez Créer une Pull Request de documentation.

Obtenir deux dépôts

Si vous n'avez pas déjà le dépôt kubernetes/website, obtenez le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website

Déterminez le répertoire de base de votre clone du dépôt kubernetes/website. Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre répertoire de base est $GOPATH/src/github.com/kubernetes/website. Les étapes restantes se réfèrent à votre répertoire de base en tant que <web-base>.

Si vous envisagez d’apporter des modifications aux documents de référence et si vous ne disposez pas déjà du dépôt kubernetes/kubernetes, obtenez-le maintenant:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Déterminez le répertoire de base de votre clone du dépôt kubernetes/kubernetes. Par exemple, si vous avez suivi l’étape précédente pour obtenir le dépôt, votre répertoire de base est $GOPATH/src/github.com/kubernetes/kubernetes. Les étapes restantes se réfèrent à votre répertoire de base en tant que <k8s-base>.

Note: Si vous devez uniquement générer, sans modifier, les documents de référence, vous n'avez pas besoin d'obtenir manuellement le dépôt kubernetes/kubernetes. Lorsque vous exécutez la commande update-imported-docs, il clone automatiquement le dépôt kubernetes/kubernetes.

Modification du code source de Kubernetes

La documentation de référence pour les composants et les outils Kubernetes est générée automatiquement à partir du code source de Kubernetes. Si vous souhaitez modifier la documentation de référence, commencez par modifier un ou plusieurs commentaires dans le code source de Kubernetes. Faites le changement dans votre dépôt local kubernetes/kubernetes, puis soumettez une pull request sur la branche master github.com/kubernetes/kubernetes.

PR 56942 est un exemple de pull request qui modifie les commentaires dans le code source de Kubernetes.

Surveillez votre pull request, et répondez aux commentaires des relecteurs. Continuez à surveiller votre pull request jusqu'à ce qu'elle soit mergée dans la branche master du dépot kubernetes/kubernetes.

Selectionnez vos commits dans une branche release

Vos commits sont sur la branche master, qui est utilisée pour le développement sur la prochaine sortie de Kubernetes. Si vous souhaitez que vos commits apparaissent dans la documentation d'une version Kubernetes déjà publiée, vous devez proposer que vos commits soit sélectionnée dans la branche de publication.

Par exemple, supposons que la branche master est utilisée pour développer Kubernetes 1.10, et vous voulez transférer vos commits sur la branche release-1.9. Pour savoir comment faire cela, consultez Propose a Cherry Pick.

Surveillez votre pull request cherry-pick jusqu'à ce qu'elle soit mergée dans la branche release.

Note: Proposer un cherry pick exige que vous ayez la permission de définir un label et un milestone dans votre pull request. Si vous ne disposez pas de ces autorisations, vous devrez travailler avec une personne pouvant définir les paramètres de labels et de milestone pour vous.

Vue générale de update-imported-docs

L'outil update-importer-docs se trouve dans le répertoire kubernetes/website/update-importer-docs/. L'outil effectue les étapes suivantes:

  1. Effectuez un clone des différents dépots spéciés dans le fichier de configuration. Afin de générer des documents de référence, les dépôts clonés par défaut sont: kubernetes-incubator/reference-docs et kubernetes/federation.
  2. Effectuez les commandes dans les dépôts clonés pour préparer le générateur de documentation et génerer les fichiers Markdown.
  3. Copiez les fichiers markdown générés dans un copie locale du dépôt kubernetes/website. Les fichiers doivent être mis dans les dossiers spécifiés dans le fichier de configuration.

Quand les fichiers Markdown sont dans votre clone local du dépot kubernetes/website, vous pouvez les soumettre dans une pull request vers kubernetes/website.

Personnaliser le fichier de configuration

Ouvrez <web-base>/update-importer-docs/reference.yml pour le modifier. Ne modifiez pas le contenu de l'entrée generate-command sauf si vous comprenez ce qu'elle fait et devez modifier la branche de release spécifiée.

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-incubator/reference-docs.git
  # Ceci et la commande generate ci-dessous nécessitent une modification lorsque les branches de référence-docs sont correctement définies
  branch: master
  generate-command: |
    cd $GOPATH
    git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
    cd src/k8s.io/kubernetes
    git checkout release-1.11
    make generated_files
    cp -L -R vendor $GOPATH/src
    rm -r vendor
    cd $GOPATH
    go get -v github.com/kubernetes-incubator/reference-docs/gen-compdocs
    cd src/github.com/kubernetes-incubator/reference-docs/
    make comp

Dans reference.yml, les attributs files est une liste d'objets ayant des attributs src et dst. L'attribut src spécifie l'emplacement d'un fichier Markdown généré, et l'attribut dst spécifie où copier ce fichier dans le dépôt local kubernetes/website. Par exemple:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-incubator/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Notez que lorsqu'il y a beaucoup de fichiers à copier du même répertoire source dans le même répertoire de destination, vous pouvez utiliser des caractères génériques dans la valeur donnée à src et vous pouvez simplement fournir le nom du répertoire comme valeur pour dst. Par exemple:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Exécution de l'outil update-importer-docs

Après avoir revu et/ou personnalisé le fichier reference.yaml, vous pouvez exécuter l'outil update-imports-docs:

cd <web-base>/update-imported-docs
./update-imported-docs reference.yml

Ajouter et valider des modifications dans kubernetes/website

Répertoriez les fichiers générés et copiés dans le dépôt kubernetes/website:

cd <web-base>
git status

La sortie affiche les fichiers nouveaux et modifiés. Par exemple, la sortie pourrait ressembler à ceci:

...

    modified:   content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
    modified:   content/en/docs/reference/command-line-tools-reference/federation-apiserver.md
    modified:   content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md
    modified:   content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
    modified:   content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
    modified:   content/en/docs/reference/command-line-tools-reference/kube-proxy.md
    modified:   content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
...

Exécutez git add et git commit pour faire un commit de ces fichiers.

Créer une pull request

Créez une pull request vers le dépôt kubernetes/website. Consultez votre pull request et répondez aux corrections suggérées par les rélecteurs jusqu'à ce que la pull request soit acceptée et mergée.

Quelques minutes après le merge votre pull request, vos références mises à jour seront visibles dans la documentation publiée.

A suivre